Skip to main content

Authentication

Every request needs a bearer token in the Authorization header:

Authorization: Bearer mdb_xxxxxxxx.yyyyyyyyyyyyyyyyyyyy

That is the only authentication header the API accepts. In particular, the Anthropic-style x-api-key header is not accepted anywhere, including on the Anthropic-compatible /v1/messages endpoint. See Anthropic compatibility for what that means for Anthropic SDKs.

API keys​

Keys are created in the console and have the format mdb_<prefix>.<secret>.

What to know about them:

  • The full key is shown once, when you create it. Afterwards the console shows only the prefix. If you lose a key, revoke it and create a new one.
  • Keys belong to you, inside your organization. Usage and billing accrue to the organization, but a teammate cannot see or revoke your keys.
  • You can have up to 50 active keys at a time. Creating more returns a 409 with code api_key_limit_reached.
  • Keys can carry an expiry date, set at creation. No expiry means the key lives until revoked.
  • Deleting a key revokes it. Revocation is immediate and permanent.
  • Billing problems don't revoke keys. If your organization's wallet runs dry, requests are refused (see Errors) but the key stays valid, and access resumes automatically once the balance recovers.

Keys are created through the console (which uses your browser session's credentials). The contract that matters for automation: an API key can never mint another API key.

What a failed authentication looks like​

Authentication is checked before the request reaches the API, so a missing, malformed, or revoked key returns an HTTP 401 whose body is typically an HTML error page (a few paths return a small JSON detail instead). Treat any 401 as "bad credentials" and don't parse its body.

Everything after authentication (unknown model, empty wallet, rate limits) returns structured JSON as described in Errors.

Checking your account from code​

Two account endpoints accept API keys and report your remaining included tokens, per-model usage, and (for the billing owner) the wallet balance. They live on a separate host, auth.mindshub.ai. The full request and response shapes are in Billing → Checking usage and balance from code.

Key hygiene​

  • Keep keys out of source control and client-side code. Anyone with the key can spend your organization's wallet.
  • Use one key per application or environment, and name keys in the console so a leaked one is easy to identify and revoke.
  • Rotate by creating the new key first, deploying it, then revoking the old one; revocation is immediate.