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. For nonce-bound BLE authorization, read the device public key (PK_D) with the mobile SDK and include it as pk_d. Bota One uses this flow before persisting the returned device token to the device. 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

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

Request Body

string
required
The ID of the end user to bind this device to.
string
Device secp256r1 public key as 64 raw bytes (x || y) encoded as exactly 128 lowercase hexadecimal characters. Read it from the connected device through the mobile SDK. Required for nonce-bound deprovision and reset grants.
Never place a Bota project API key in the mobile app. The app sends device_id, end_user_id, and pk_d to your backend; your backend calls this endpoint and returns only the bind result needed by the app.

Response

Returns the device object with a device_token field. When device-certificate issuance is enabled for the project, the response can also include one-time cert material for delivery to compatible firmware.

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.
Treat cert.privkey_pem as a secret. Do not persist it in the app, analytics, or logs. Deliver it immediately through the SDK. The current demo treats delivery failure as non-fatal because device-token TLS remains the compatibility path; projects enforcing mTLS must instead fail or recover binding explicitly.