Concepts

API Keys

API keys authenticate requests to the MUDBASE API. Create and manage keys in the Console.

Sending a key

Include your key on every request as the X-API-Key header:

bash
curl https://api.mudbase.dev/api/projects/{projectId}/collections/{collectionId}/data \
  -H "X-API-Key: ak_live_..."
curl https://api.mudbase.dev/api/projects/{projectId}/collections/{collectionId}/data \
  -H "X-API-Key: ak_live_..."

A key is scoped to the single project it was created under — it cannot read or write another project's data, even inside the same organization, regardless of what permissions it was granted.

Scopes (resource + action)

Every key is granted a set of resource / action permissions when it's created, and you can edit them later without regenerating the key. Grant only what a given integration actually needs.

Resources you can scope a key to:

  • database — Collections and documents (Collection Data CRUD)
  • storage — Buckets and files
  • functions — Trigger and read serverless functions
  • realtime — WebSocket / SSE channels
  • messaging — Chat and messaging
  • auth — End-user auth operations
  • wallet — Wallet balances and addresses
  • transactions — Broadcast and read blockchain transactions
  • addons — Invoke and read add-on jobs
  • kyc — Start and check identity verification sessions
  • payments — Payment processing and stablecoin operations

Each resource can be granted independently for create, read, update, and delete. A key with only database:read can list and fetch documents but can't write, delete, or touch any other resource.

Rate limits

Each key has its own rate limit, independent of your plan's overall API call allowance — by default 1,000 requests per hour. You can raise or lower this per key from the Console when you create or edit it. Exceeding it returns 429 API key rate limit exceeded.

Expiry

Keys can be set to expire in 30 days, 90 days, 1 year, or effectively never (10 years). An expired key is rejected with 401 API key expired — rotate it by creating a new key with the same scopes before the old one expires.

Best practices

  • Never expose a key in client-side code, a public repo, or a URL query string — use it only from your own backend.
  • Create a separate key per integration (e.g. one for your CI pipeline, one for a specific service) so you can revoke one without affecting the others.
  • Grant only the resource/action pairs that integration actually calls.
  • Rotate keys periodically, especially after any team member with access to one leaves.
  • If a key is exposed anywhere (a log, a screenshot, a chat message), treat it as compromised — delete it from the Console immediately rather than hoping it wasn't misused.
Warning
A key's raw value is shown exactly once, right after you create or regenerate it. Copy it immediately — the Console never displays it again, only whether one is set.

See Authentication for how API keys compare to user Bearer tokens, or Rate Limits for how per-key limits interact with your plan's overall limits.