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.

​
Authentication

Requires an API key with devices:write scope. 
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"
  }'

​
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. 
{
  "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"
}

​
Response Fields

FieldTypeDescription
idstringDevice identifier (dev_*)
serial_numberstringPhysical serial number
modelstringDevice model (bota_pin or bota_note)
firmware_versionstring | nullCurrent firmware version
statusstringbound (always bound after successful bind)
end_user_idstringBound end user (eu_*)
device_tokenstringDevice authentication token (dtok_*). Shown only once — store it securely.
battery_percentinteger | nullBattery level (0-100)
storage_used_mbinteger | nullStorage used in MB
storage_total_mbinteger | nullTotal storage capacity in MB
signal_strength_dbminteger | nullSignal strength in dBm
last_heartbeat_atstring | nullLast heartbeat timestamp (ISO 8601)
recording_stateobject | nullCurrent recording state
metadataobjectCustom key-value metadata
created_atstringCreation timestamp (ISO 8601)
updated_atstringLast update timestamp (ISO 8601)

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