Devices API | Bootspring Docs

Manage authorized devices for CLI and desktop applications.

Endpoints#

Method	Endpoint	Description
`GET`	`/devices`	List authorized devices
`GET`	`/devices/:id`	Get device details
`DELETE`	`/devices/:id`	Revoke device authorization
`POST`	`/devices/authorize`	Start device authorization
`POST`	`/devices/token`	Exchange device code for token

Device Object#

{
  "id": "dev_abc123",
  "name": "MacBook Pro",
  "type": "cli",
  "platform": "darwin",
  "arch": "arm64",
  "hostname": "johns-macbook",
  "lastActiveAt": "2024-01-15T10:30:00Z",
  "lastIp": "192.168.1.100",
  "location": {
    "city": "San Francisco",
    "country": "US"
  },
  "createdAt": "2024-01-01T00:00:00Z"
}

List Devices#

GET /devices

Query Parameters#

Parameter	Type	Description
`type`	string	Filter by type: `cli`, `desktop`, `other`
`active`	boolean	Only active devices (last 30 days)

Example Request#

curl https://api.bootspring.dev/v1/devices \
  -H "Authorization: Bearer bs_xxx"

Response#

{
  "data": [
    {
      "id": "dev_abc123",
      "name": "MacBook Pro",
      "type": "cli",
      "platform": "darwin",
      "arch": "arm64",
      "hostname": "johns-macbook",
      "lastActiveAt": "2024-01-15T10:30:00Z",
      "current": true,
      "createdAt": "2024-01-01T00:00:00Z"
    },
    {
      "id": "dev_def456",
      "name": "Windows Desktop",
      "type": "cli",
      "platform": "win32",
      "arch": "x64",
      "hostname": "DESKTOP-ABC123",
      "lastActiveAt": "2024-01-10T08:00:00Z",
      "current": false,
      "createdAt": "2024-01-05T00:00:00Z"
    }
  ]
}

Get Device#

GET /devices/:id

Example Request#

curl https://api.bootspring.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer bs_xxx"

Response#

{
  "data": {
    "id": "dev_abc123",
    "name": "MacBook Pro",
    "type": "cli",
    "platform": "darwin",
    "arch": "arm64",
    "hostname": "johns-macbook",
    "cliVersion": "1.2.0",
    "lastActiveAt": "2024-01-15T10:30:00Z",
    "lastIp": "192.168.1.100",
    "location": {
      "city": "San Francisco",
      "region": "CA",
      "country": "US"
    },
    "sessions": {
      "total": 45,
      "lastWeek": 12
    },
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Revoke Device#

DELETE /devices/:id

Example Request#

curl -X DELETE https://api.bootspring.dev/v1/devices/dev_abc123 \
  -H "Authorization: Bearer bs_xxx"

Response#

{
  "data": {
    "revoked": true,
    "id": "dev_abc123"
  }
}

Note: Revoking a device invalidates all tokens issued to that device.

Start Device Authorization#

POST /devices/authorize

This initiates the device authorization flow for CLI tools.

Request Body#

Field	Type	Required	Description
`clientId`	string	Yes	Application identifier
`scope`	string	No	Requested permission scopes
`deviceInfo`	object	No	Device metadata

Example Request#

curl -X POST https://api.bootspring.dev/v1/devices/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "bootspring-cli",
    "scope": "read:projects write:projects invoke:agents",
    "deviceInfo": {
      "platform": "darwin",
      "arch": "arm64",
      "hostname": "johns-macbook"
    }
  }'

Response#

{
  "data": {
    "deviceCode": "dev_code_xyz789...",
    "userCode": "ABCD-1234",
    "verificationUri": "https://bootspring.dev/device",
    "verificationUriComplete": "https://bootspring.dev/device?code=ABCD-1234",
    "expiresIn": 900,
    "interval": 5
  }
}

Exchange Device Code#

POST /devices/token

Poll this endpoint to exchange the device code for an access token.

Request Body#

Field	Type	Required	Description
`clientId`	string	Yes	Application identifier
`deviceCode`	string	Yes	Device code from authorize
`grantType`	string	Yes	Must be `urn:ietf:params:oauth:grant-type:device_code`

Example Request#

curl -X POST https://api.bootspring.dev/v1/devices/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "bootspring-cli",
    "deviceCode": "dev_code_xyz789...",
    "grantType": "urn:ietf:params:oauth:grant-type:device_code"
  }'

Pending Response#

{
  "error": "authorization_pending",
  "error_description": "User has not yet authorized this device"
}

Success Response#

{
  "data": {
    "accessToken": "bsd_live_abc123...",
    "tokenType": "Bearer",
    "expiresIn": 31536000,
    "scope": "read:projects write:projects invoke:agents",
    "refreshToken": "bsr_xyz789...",
    "device": {
      "id": "dev_new123",
      "name": "johns-macbook"
    }
  }
}

Rename Device#

PATCH /devices/:id

Request Body#

{
  "name": "Work MacBook Pro"
}

Response#

Returns the updated device object.

Device Limits by Plan#

Plan	Max Devices
Free	2
Pro	5
Team	20 per user
Enterprise	Unlimited

Activity Tracking#

Each device tracks:

Sessions: Number of CLI sessions
Commands: Most used commands
Projects: Projects accessed
Location: Approximate location from IP

View activity:

GET /devices/:id/activity

{
  "data": {
    "sessions": {
      "total": 45,
      "lastWeek": 12,
      "avgDuration": "15m"
    },
    "topCommands": [
      { "command": "agent invoke", "count": 89 },
      { "command": "skill apply", "count": 45 },
      { "command": "generate", "count": 32 }
    ],
    "projectsAccessed": [
      { "id": "proj_abc", "name": "My App", "count": 34 }
    ]
  }
}

Security#

Suspicious Activity Detection#

Bootspring monitors for:

Logins from new locations
Multiple failed authentication attempts
Unusual access patterns

Automatic Revocation#

Devices may be automatically revoked for:

90 days of inactivity
Security policy violations
Account suspension

Errors#

Code	Description
`device_not_found`	Device doesn't exist
`device_limit_exceeded`	Maximum devices reached
`authorization_pending`	User hasn't authorized yet
`expired_token`	Device code expired
`access_denied`	User denied authorization
`slow_down`	Polling too frequently