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:

curl -H "X-API-Key: bk_live_abc123..." \
     https://api.bodha.run/api/v1/routes

Alternatively, you can pass it as a Bearer token:

curl -H "Authorization: Bearer bk_live_abc123..." \
     https://api.bodha.run/api/v1/routes

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

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:

{
  "error": "insufficient_scope",
  "message": "This endpoint requires scopes: orders:write",
  "missing": ["orders:write"]
}

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

{
  "error": "ip_not_allowed",
  "message": "Request IP is not in the API key allowlist."
}

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

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.