# Authentication and API keys

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.

```bash
curl https://api.mirabase.dev/v2/whoami \
  -H "Authorization: Bearer $MIRABASE_API_KEY"
```

> **Warning:** 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`](https://mirabase.io/developers/api/discovery.md#discovery-llms) and [`GET /v2/openapi.yaml`](https://mirabase.io/developers/api/discovery.md#discovery-openapi) work without credentials.

## Create a key in the console

The [console](https://console.mirabase.dev) 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`](https://mirabase.io/developers/api/api-keys.md#apikeys-create) 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:

```bash
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"}'
```

TypeScript:

```ts
const key = await mirabase.keys.create({
  actor_id: principalId,
  name: "ci-reader",
  grant_capabilities: ["knowledge:read"],
  allowed_space_ids: [spaceId],
  expires_at: "2027-01-01T00:00:00Z",
});
```

Python:

```python
key = mb.keys.create({
    # The principal the key acts as: here, yourself.
    "actor_id": me["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](https://mirabase.io/developers/api/api-keys.md#apikeys-create); 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](https://mirabase.io/developers/api/api-keys.md#apikeys-create.body.metadata_scope); for how its writes are labeled, see [DevMetadataScope](https://mirabase.io/developers/api/schemas.md#DevMetadataScope).

```bash
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](https://console.mirabase.dev).
- 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](https://mirabase.io/developers/concepts.md#space-per-user).

## Check what a key can do

[`GET /v2/whoami`](https://mirabase.io/developers/api/identity.md#identity-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](https://mirabase.io/developers/permissions.md#capabilities).

## Rotate or replace a key

[`POST /v2/api-keys/{key_id}/rotate`](https://mirabase.io/developers/api/api-keys.md#apikeys-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`](https://mirabase.io/developers/api/api-keys.md#apikeys-create).
2. Switch your callers to the new key.
3. Revoke the old key with [`DELETE /v2/api-keys/{key_id}`](https://mirabase.io/developers/api/api-keys.md#apikeys-revoke).

> **Note:** 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`](https://mirabase.io/developers/api/api-keys.md#apikeys-list) until an admin revokes it.

## Find unused keys

Every key carries `last_used_at`: when it last called the API (see [DevApiKey](https://mirabase.io/developers/api/schemas.md#DevApiKey.last_used_at)). 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](https://console.mirabase.dev) shows it too.

## Revoke a key

Once [`DELETE /v2/api-keys/{key_id}`](https://mirabase.io/developers/api/api-keys.md#apikeys-revoke) 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](https://mirabase.app/en/contact) with the account's email and its `tenant_id`, which [`GET /v2/whoami`](https://mirabase.io/developers/api/identity.md#identity-whoami) returns.

- Deleted data cannot be recovered. Take the files you want to keep with an [export](https://mirabase.io/developers/sync.md#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](https://mirabase.io/developers/files.md#delete) files and [forget](https://mirabase.io/developers/memory.md#govern) memories yourself.

## Next steps

- [SDK](https://mirabase.io/developers/sdks.md): install a client instead of building requests by hand.
- [Permissions](https://mirabase.io/developers/permissions.md): how capabilities combine, and how to limit a key to certain Spaces and directories.
- [Connect an Agent](https://mirabase.io/developers/agents.md): give an Agent its own principal and key.
