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

# Authentication

> How to authenticate requests to the Bodha API.

# Authentication

Every request to the Bodha API must include a valid API key. Keys are scoped to
your organisation and carry specific permissions.

## Passing the key

Include your key in the `X-API-Key` header:

```bash theme={null}
curl -H "X-API-Key: bk_live_abc123..." \
     https://api.bodha.run/api/v1/routes
```

Alternatively, you can pass it as a Bearer token:

```bash theme={null}
curl -H "Authorization: Bearer bk_live_abc123..." \
     https://api.bodha.run/api/v1/routes
```

## Key formats

| Prefix | Environment | Description |
| - | - | - |
| `bk_live_` | Production | Access real data. |
| `bk_test_` | Test | Safe for development — same endpoints, isolated data. |

## Scopes

Each key is created with specific scopes that control what it can access:

| Scope | Description |
| - | - |
| `routes:read` | List and read routes |
| `routes:write` | Create and update routes |
| `stops:read` | Read stop details |
| `stops:write` | Update stop data and status |
| `orders:read` | List and read orders |
| `orders:write` | Create, update, and delete orders |
| `customers:read` | Read customer records |
| `customers:write` | Create and update customers |
| `drivers:read` | Read driver information |
| `depots:read` | Read depot locations |
| `webhooks:manage` | Create and manage webhook endpoints |

If a request needs a scope the key doesn't have, the API returns `403`:

```json theme={null}
{
  "error": "insufficient_scope",
  "message": "This endpoint requires scopes: orders:write",
  "missing": ["orders:write"]
}
```

## IP allowlists

You can optionally restrict a key to specific IP addresses. Requests from other
IPs receive a `403` response:

```json theme={null}
{
  "error": "ip_not_allowed",
  "message": "Request IP is not in the API key allowlist."
}
```

## Key management

Manage your keys in **Settings → Developer Portal**, or via the internal
developer endpoints:

* **Create** — generates a new key (shown once)
* **Revoke** — immediately invalidates a key
* **List** — see all keys with their scopes and last-used timestamp

> [!WARNING]
>
> Your full API key is shown **only once** at creation. Store it securely — you
> cannot retrieve it later. If lost, revoke it and create a new one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.