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

​
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) - device_id and end_user_id are auto-populated from the token
  • 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)
Automatic Parameter Extraction: When a device token is used, the backend automatically extracts the device_id and end_user_id from the token’s database record. Devices should NOT include these fields in request bodies - they will be ignored and overridden with the token’s values.
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:

​
Test vs Live Keys

Bota provides separate key types for development and production:
Key PrefixPurpose
sk_live_Production data, billed usage
sk_test_Development and testing, no charges
Use test keys during development. Consider creating separate projects for staging environments.

​
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.
When you create a new API key, copy it immediately and store it securely. The full key is only shown once - after creation, you’ll only see a hint like sk_live_...vVkA in the dashboard.

​
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 displays:
  • Key hint (e.g., sk_live_...vVkA) - for identification
  • Name - optional user-defined label
  • Last used - timestamp of most recent API call
  • Created - when the key was generated
API keys are shown in full only once upon creation. After that, only the hint is displayed (e.g., sk_live_...vVkA). If you lose a key, you must create a new one and revoke the old one.
Device tokens are managed through the API: