> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bota.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Bota API

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 Type         | Prefix                  | Lifetime              | Use Case                 |
| ---------------- | ----------------------- | --------------------- | ------------------------ |
| **Secret Key**   | `sk_live_` / `sk_test_` | Long-lived            | Server-side API calls    |
| **Device Token** | `dtok_`                 | Long-lived            | 4G device direct uploads |
| **Upload Token** | `up_`                   | 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.

```bash theme={null}
curl https://api.bota.dev/v1/end-users \
  -H "Authorization: Bearer sk_live_abc123..."
```

<Warning>
  Never expose secret keys in mobile apps, browser code, or public repositories. They provide full access to your project.
</Warning>

### 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](/api-reference/devices/bind)
* **Scoped to a single device** and its bound end user
* **Limited in permissions** - can only create/upload recordings and report device status

```bash theme={null}
# 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`)

<Info>
  **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.
</Info>

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

### 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:

```mermaid theme={null}
sequenceDiagram
    participant Backend as Your Backend
    participant API as Bota API

    Backend->>API: POST /end-users<br/>Authorization: Bearer sk_live_...
    API-->>Backend: 201 Created
```

### 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 Bluetooth device via your app:

```mermaid theme={null}
sequenceDiagram
    participant Device
    participant App as Mobile App
    participant Backend as Your Backend
    participant API as Bota API
    participant S3 as Bota S3

    Device->>App: 1. Bluetooth transfer audio
    App->>Backend: 2. Request upload URL
    Backend->>API: 3. POST /recordings (sk_live_)
    API-->>Backend: 4. Recording created
    Backend->>API: 5. POST /recordings/:id/upload-url
    API-->>Backend: 6. Pre-signed URL
    Backend-->>App: 7. Upload URL
    App->>S3: 8. PUT audio file
```

### 4G Device Direct Upload Flow

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

```mermaid theme={null}
sequenceDiagram
    participant Device as 4G Device
    participant API as Bota API
    participant S3 as Bota S3

    Note over Device: Device has dtok_* from initial bind

    Device->>API: 1. POST /recordings<br/>Authorization: Bearer dtok_...
    API-->>Device: 2. Recording created

    Device->>API: 3. POST /recordings/:id/upload-url
    API-->>Device: 4. Pre-signed URL

    Device->>S3: 5. PUT audio file

    Device->>API: 6. POST /recordings/:id/upload-complete
    API-->>Device: 7. Recording status: uploaded
```

### Device Provisioning Flow

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

```mermaid theme={null}
sequenceDiagram
    participant Device
    participant App as Mobile App
    participant Backend as Your Backend
    participant API as Bota API

    Device->>App: 1. Bluetooth pairing
    Device->>App: 2. Send serial number

    App->>Backend: 3. Register device
    Backend->>API: 4. POST /devices
    API-->>Backend: Device created

    App->>Backend: 5. Bind to user
    Backend->>API: 6. POST /devices/:id/bind
    API-->>Backend: Device + device_token

    Backend-->>App: 7. Device token
    App->>Device: 8. Provision dtok_* via BLE
```

## Test vs Live Keys

Bota provides separate key types for development and production:

| Key Prefix | Purpose                             |
| ---------- | ----------------------------------- |
| `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

<AccordionGroup>
  <Accordion title="Store keys securely">
    Use environment variables or a secrets manager. Never commit keys to version control.

    ```bash theme={null}
    # Good: Environment variable
    export BOTA_API_KEY=sk_live_...

    # Bad: Hardcoded in source
    const apiKey = 'sk_live_...'; // Never do this!
    ```
  </Accordion>

  <Accordion title="Use restricted keys when possible">
    If a service only needs to read transcriptions, create a restricted key with only `transcriptions:read` scope.
  </Accordion>

  <Accordion title="Rotate keys periodically">
    Rotate your API keys regularly and immediately if you suspect a compromise. For device tokens, use the [token refresh](/api-reference/devices/refresh-token) endpoint.
  </Accordion>

  <Accordion title="Never expose keys in client code">
    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.
  </Accordion>

  <Accordion title="Verify webhook signatures">
    Always verify the `X-Bota-Signature` header when receiving webhooks to prevent spoofing.
  </Accordion>

  <Accordion title="Secure device token storage">
    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.
  </Accordion>

  <Accordion title="Save keys immediately after creation">
    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.
  </Accordion>
</AccordionGroup>

## Managing API Keys

API keys are managed in the [Bota Dashboard](https://platform.bota.dev):

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

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

Device tokens are managed through the API:

* **Create**: Issued automatically when [binding a device](/api-reference/devices/bind)
* **Refresh**: Use the [token refresh](/api-reference/devices/refresh-token) endpoint
* **Revoke**: Automatically revoked when [unbinding a device](/api-reference/devices/unbind)