Authentication

Lumbox accepts two auth schemes against the same API key. Use whichever fits your client.

Bearer (recommended)

curl https://api.lumbox.co/v1/inboxes \
  -H "Authorization: Bearer ak_your_key_here"

This matches what most SDKs, the MCP HTTP transport, and standard OpenAPI tooling expect.

X-API-Key (also supported)

curl https://api.lumbox.co/v1/inboxes \
  -H "X-API-Key: ak_your_key_here"

Functionally identical to Bearer. Keep using this if your existing code already does.

OAuth 2.1

For remote MCP clients and any third-party app that should authorize on behalf of a Lumbox user, Lumbox runs an OAuth 2.1 authorization server with Dynamic Client Registration. See Remote MCP for the connector flow. The protected-resource metadata is at https://api.lumbox.co/.well-known/oauth-protected-resource.

Getting an API Key

1. Sign up at lumbox.co
2. Go to Settings > API Keys
3. Click Create API Key
4. Copy the key. It's only shown once.

Agents that need to onboard themselves with no human-issued key can use Agent Self-Signup instead.

Scoped Keys

API keys can be scoped to specific inboxes. Org-wide:

curl -X POST https://api.lumbox.co/v1/orgs/me/api-keys \
  -H "Authorization: Bearer ak_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "github-bot-key", "allowed_inbox_ids": ["inb_abc123"]}'

Or mint a key directly on a single inbox (key inherits that inbox as its only scope):

curl -X POST https://api.lumbox.co/v1/inboxes/inb_abc123/api-keys \
  -H "Authorization: Bearer ak_admin_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "github-bot-key"}'

A scoped key that hits an inbox outside its allow-list returns 403 Forbidden.

Key Format

API keys are prefixed with ak_ followed by a random string. Example: ak_7f3a9b2c4d…