Skip to main content
POST
Bind a device to an end user. A device can only be bound to one user at a time. If you need to reassign a device, unbind it first. When a device is bound, a device token (dtok_*) is returned. This token enables 4G-equipped devices to upload recordings directly to the Bota API without requiring a companion mobile app.
The device token is only shown once in the bind response. Store it securely on the device. If lost, you must unbind and rebind the device to get a new token.

Authentication

Requires an API key with devices:write scope.

Path Parameters

id
string
required
The device’s unique identifier (e.g., dev_abc123).

Request Body

end_user_id
string
required
The ID of the end user to bind this device to.

Response

Returns the device object with a device_token field.

Response Fields

Device Token

The device_token returned in the response is a limited-permission credential that allows the device to:
  • Create recordings (POST /v1/recordings)
  • Get upload URLs (POST /v1/recordings/:id/upload-url)
  • Mark uploads complete (POST /v1/recordings/:id/upload-complete)
  • Report device status (POST /v1/devices/:id/heartbeat)
  • Refresh its token (POST /v1/devices/:id/token/refresh)
The device token is automatically scoped to the bound end user - recordings created with this token are automatically associated with the correct end user.
Device tokens have very limited permissions compared to API keys. They cannot list recordings, access other users’ data, or perform administrative operations.
A device can only be bound to one end user at a time. Attempting to bind an already-bound device returns a 409 Conflict error. Use the Unbind Device endpoint first.