> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create, rotate and revoke API keys

> An API key lets a backend service, a script, a CI job or an MCP client call MITHUNAI with a role of its own. Create one, send it, rotate it, revoke it.

An API key lets software that is not a browser, such as a backend service, a script, a CI job or an MCP client, call MITHUNAI. Each key belongs to one organisation and holds one [role](/concepts/organizations-and-roles), exactly as a person would.

## Create a key

Only Owners and Administrators can create keys, and only from a signed-in console session. An API key cannot create, list or revoke keys, so a leaked key can never mint itself a replacement.

1. Open **Operations → API keys** and select **New API key**.

2. Enter a **Name** that says what uses it, such as "Support portal integration". It appears in your audit trail.

3. Choose a **Role**. Pick the narrowest that works:

   | Role                         | Suits                                                                         |
   | ---------------------------- | ----------------------------------------------------------------------------- |
   | **Member**                   | Integrations and MCP clients that only ask questions. The recommended default |
   | **Knowledge operator**       | Ingestion pipelines that manage sources and documents                         |
   | **Editor**                   | Automation that manages assistants and knowledge                              |
   | **Administrator**, **Owner** | Full administration. Rarely needed by an integration                          |

   You cannot create a key with a role above your own.

4. Choose when it **Expires**: 30 days, 90 days, 1 year or never. An expiring key limits how long a leaked credential stays useful.

5. Select **Create**, then **copy the key now**. It is shown once and cannot be retrieved later.

## Use a key

Send it as a bearer token:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "$MITHUNAI_URL/arukz/api/v1/assistants" \
  --header "Authorization: Bearer $MITHUNAI_API_KEY"
```

A key always acts in the organisation it was created in. Each key has its own rate-limit budget, so one busy integration cannot exhaust another's.

## Rotate a key

Rotation is two steps, so nothing breaks in between:

1. Create a new key with the same role, and deploy it to the integration.
2. Once the integration is using the new key, revoke the old one.

The **Last used** column shows whether the old key is still in use before you revoke it.

## Revoke a key

Select **Revoke** next to the key in **Operations → API keys**. Revocation:

* takes effect on the **next request**, with no delay or cache;
* is **permanent**: a revoked key cannot be reactivated;
* keeps the key in the list as revoked, so access reviews can see it existed.

<Danger>
  If a key is exposed, in a commit, a log, a support ticket or a web page, revoke it first, then
  create a replacement.
</Danger>

## Keep keys safe

* Store keys in a secret manager, never in source code or a committed `.env` file.
* Never put a key in a browser, a mobile app or any HTML. For websites, use the [widget](/channels/widget), which has its own public key.
* Give each integration its own key, so you can revoke one without affecting the others.
* Set an expiry where you can, and review **Last used** regularly to revoke keys nobody uses.

## Errors

| Situation                                                  | Response                                                             |
| ---------------------------------------------------------- | -------------------------------------------------------------------- |
| The key is missing, malformed, unknown, revoked or expired | `401 authentication_error`. All of these look the same, deliberately |
| The key's role does not allow the action                   | `403 authorization_error`                                            |
| The key is used to manage API keys                         | `403 authorization_error`                                            |
| The resource belongs to another organisation               | `404 not_found`                                                      |

For the endpoints, see [API keys in the API reference](/api-reference/api-keys/create-api-key).