Skip to content
Developer docs
Docs menu

Authentication and API keys

Markdown

Send, create, limit, rotate, and revoke API keys.

Send an API key

Send Authorization: Bearer mb_live_... on every request. The token is 256 random bits, not a JWT, so it contains no readable data. The service stores only a hash and looks it up on every request.

curl
curl https://api.mirabase.dev/v2/whoami \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
Keep keys on a server. Never put one in frontend code, a mobile app, or a public repository. Revoke a key as soon as you suspect it leaked.

Only GET /llms.txt and GET /v2/openapi.yaml work without credentials.

Create a key in the console

The console creates, narrows, rotates, and revokes API keys. Your first key comes from there: signing up does not issue one. The console shows the secret only once.

A console session manages the account and serves the console's own features: listing and deleting files, processing progress, the retrieval playground, and request logs. Reading file content and writing files accept API keys alone. While the account is pending approval, a session can only manage API keys and view the account and the read-only lists; other requests return 403 account_pending_approval.

Create a key through the API

POST /v2/api-keys issues a key. Only a tenant_admin can issue one, and an Agent cannot issue its own; a new key cannot be wider than its issuer in capabilities, Spaces, or expiry. token appears in this response only, so store it now.

curl
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$PRINCIPAL_ID'", "name": "ci-reader",
       "grant_capabilities": ["knowledge:read"],
       "allowed_space_ids": ["'$SPACE_ID'"],
       "expires_at": "2027-01-01T00:00:00Z"}'

In an account with a team, which principals and keys an Admin can manage is in the description of issuing a key; the Owner is not subject to these rules.

Limit a key by metadata

Send metadata_scope when issuing a key, and the key only sees Entries that carry the matching metadata labels. Different metadata keys combine with AND, and multiple values of one metadata key combine with OR. For the operations such a key can call, see the metadata_scope parameter; for how its writes are labeled, see DevMetadataScope.

curl
curl -X POST https://api.mirabase.dev/v2/api-keys \
  -H "Authorization: Bearer $MIRABASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": "'$PRINCIPAL_ID'", "name": "acme-agent",
       "grant_capabilities": ["knowledge:read", "knowledge:answer", "knowledge:write"],
       "metadata_scope": {"customer": ["acme", "shared"]}}'
  • The service checks the scope on every request, and the caller cannot bypass it.
  • Near-duplicate replacement and memory revision only relate Entries with the same values under the scope keys, so one customer's writes never affect another's content.
  • Account memories carry no labels and are not visible to a key with a scope.
  • Over MCP, tools/list shows a key with a scope only the tools it can call. You can also issue a key with a scope on the API keys page of the console.
  • A scope does not hide the names and external_id of Spaces. For a hard boundary between end users, give each user a Space. See One Space per end user.

Check what a key can do

GET /v2/whoami returns the principal, the key, and the effective capabilities. Check it after a 403: when effective_capabilities is narrower than principal.capabilities, or key.allowed_space_ids is set, the key is the limit, not the principal. For how the service computes effective capabilities, see Capabilities.

Rotate or replace a key

POST /v2/api-keys/{key_id}/rotate issues a new key and revokes the old one in a single transaction, with no overlap. A key cannot rotate itself: if the response were lost, the caller would have no credentials left. To replace the key you are using:

  1. Issue a new key with POST /v2/api-keys.
  2. Switch your callers to the new key.
  3. Revoke the old key with DELETE /v2/api-keys/{key_id}.
If the response to the issue is lost, the old key still works: issue again under a new Idempotency-Key. The unused key stays in GET /v2/api-keys until an admin revokes it.

Find unused keys

Every key carries last_used_at: when it last called the API (see DevApiKey). Use it to clean up idle keys and to see whether the recipient has started using a key you handed out; the key list in the console shows it too.

Revoke a key

Once DELETE /v2/api-keys/{key_id} returns, the next request with that key returns 401, and no write it started can still commit. Revocation does not cascade: after a leak, use each key's issued_by_key_id to find the keys it issued and revoke them one by one.

Delete your account

To delete your account and all of its data, contact us with the account's email and its tenant_id, which GET /v2/whoami returns.

  • Deleted data cannot be recovered. Take the files you want to keep with an export first; exports hold files only, without memories or version history.
  • To remove only some of your content you do not need to contact us: erase files and forget memories yourself.

Next steps

  • SDK: install a client instead of building requests by hand.
  • Permissions: how capabilities combine, and how to limit a key to certain Spaces and directories.
  • Connect an Agent: give an Agent its own principal and key.