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 carrying the standard error envelope, on every endpoint including the OpenAI-compatible ones:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or missing credentials. See https://docs.mindshub.ai/inference/authentication"}}

Treat any 401 as "bad credentials" and do not retry it. The check accepts a browser session as well as an API key, which is why the message says credentials rather than key. A 403 arrives in the same shape with error.type of permission_error: the credential is real, but it is not allowed to use that resource. A key whose user has left the organization it belongs to is the usual cause. Do not retry that either. See Errors.

Your credentials are checked twice, once at the edge and once at the deeper authorization gate every request passes on its way to a model. Both produce the same body shape and the same statuses, so you do not need to tell them apart.

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.