Skip to main content
Bota uses project-scoped API keys to authenticate requests. This guide covers the different key types, authentication flows, and security best practices.

​
API Key Types

Key TypePrefixLifetimeUse Case
Secret Keysk_live_ / sk_test_Long-livedServer-side API calls
Restricted Keyrk_live_ / rk_test_Long-livedLimited-scope server calls
Device Tokendtok_Long-lived4G device direct uploads
Upload Tokenup_Short-lived (minutes)Single recording upload

​
Secret Keys

Secret keys provide full access to your project’s API. Use them only on your backend server. 
curl https://api.bota.dev/v1/end-users \
  -H "Authorization: Bearer sk_live_abc123..."
Never expose secret keys in mobile apps, browser code, or public repositories. They provide full access to your project.

​
Restricted Keys

Restricted keys allow you to limit permissions for specific use cases. Create them in the Bota dashboard with only the scopes you need.
ScopeDescription
recordings:readRead recording metadata
recordings:writeCreate recordings and uploads
transcriptions:readRead transcription results
transcriptions:writeTrigger transcription jobs
end_users:readRead end user data
end_users:writeCreate/update end users
devices:readRead device data
devices:writeCreate/update/bind devices

​
Device Tokens

Device tokens (dtok_*) authenticate 4G-enabled wearable devices for direct cloud uploads. Unlike other key types, device tokens are:
  • Issued automatically when a device is bound to an end user
  • Scoped to a single device and its bound end user
  • Limited in permissions - can only create/upload recordings and report device status
# Device creating a recording
curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer dtok_abc123..."
Device tokens can:
  • Create recordings (POST /v1/recordings)
  • Get upload URLs (POST /v1/recordings/:id/upload-url)
  • Complete uploads (POST /v1/recordings/:id/upload-complete)
  • Send heartbeats (POST /v1/devices/:id/heartbeat)
  • Refresh their token (POST /v1/devices/:id/token/refresh)
Device tokens are returned only once when a device is bound. Store them securely on the device. If lost, unbind and rebind the device to get a new token.

​
Upload Tokens

Upload tokens authorize a single audio upload. They expire in minutes and are recording-scoped. 
# Use with pre-signed S3 URL
PUT https://bota-uploads.s3.amazonaws.com/...?X-Amz-Security-Token=up_abc123...

​
Authentication Flows

​
Server-to-Server

Your backend authenticates directly with Bota using secret keys. For example, creating an end user:

​
Mobile App Flow (BLE Devices)

Mobile apps authenticate through your backend, never directly with Bota. Here’s an example of uploading a recording from a BLE device via your app:

​
4G Device Direct Upload Flow

4G-enabled devices authenticate directly with Bota using device tokens, bypassing the need for a mobile app:

​
Device Provisioning Flow

Devices are provisioned during initial setup, typically via BLE pairing through your mobile app:

​
Environment Separation

Bota provides separate environments for development and production:
EnvironmentBase URLKey Prefix
Productionhttps://api.bota.dev/v1sk_live_, rk_live_
Sandboxhttps://api.sandbox.bota.dev/v1sk_test_, rk_test_
Use sandbox keys during development to avoid affecting production data.

​
Security Best Practices

Use environment variables or a secrets manager. Never commit keys to version control.
# Good: Environment variable
export BOTA_API_KEY=sk_live_...

# Bad: Hardcoded in source
const apiKey = 'sk_live_...'; // Never do this!
If a service only needs to read transcriptions, create a restricted key with only transcriptions:read scope.
Rotate your API keys regularly and immediately if you suspect a compromise. For device tokens, use the token refresh endpoint.
Mobile apps and web frontends should never contain Bota API keys. Always proxy through your backend. Device tokens are the exception - they’re designed to be stored on devices.
Always verify the X-Bota-Signature header when receiving webhooks to prevent spoofing.
On 4G devices, store the device token in secure storage (encrypted flash, secure element if available). The token grants upload access to the bound user’s recordings.

​
Managing API Keys

API keys are managed in the Bota Dashboard:
  1. Navigate to your project settings
  2. Select API Keys
  3. Create, rotate, or revoke keys as needed
Each key shows its last used timestamp and can be revoked instantly if compromised. Device tokens are managed through the API: