Skip to main content
POST
/
devices
/
{id}
/
bind
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/bind \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "eu_xyz789"
  }'

{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "model": "bota_pin",
  "firmware_version": "1.2.0",
  "status": "bound",
  "end_user_id": "eu_xyz789",
  "metadata": {},
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T11:00:00Z",
  "device_token": "dtok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
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.
​
id
string
required
The device’s unique identifier (e.g., dev_abc123).
​
end_user_id
string
required
The ID of the end user to bind this device to.
curl -X POST https://api.bota.dev/v1/devices/dev_abc123/bind \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "end_user_id": "eu_xyz789"
  }'

{
  "id": "dev_abc123",
  "serial_number": "SN-2025-001234",
  "model": "bota_pin",
  "firmware_version": "1.2.0",
  "status": "bound",
  "end_user_id": "eu_xyz789",
  "metadata": {},
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T11:00:00Z",
  "device_token": "dtok_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}

​
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.