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

# API keys

> Generate and manage keys that authenticate your agent's programmatic interfaces.

API keys authenticate calls to your agent's OpenAI-compatible REST API and MCP server. Both interfaces use the same key format.

Click the docs icon on the page header for a quick-jump to this page.

## Generating a key

1. Open your agent and go to **API Keys** in the sidebar.
2. Click **Generate new key**, optionally giving it a **label** and free-form **agent notes** (the notes are visible to the agent itself when this key is used — useful for telling the agent who or what the caller is).
3. Copy the key from the dialog — **you will not be able to see it again**.

Keys start with `sk_ah_`. Each key is bound to the agent you generated it from; it cannot be used to access other agents. Up to **10 active keys per agent** are supported — revoke one before creating an eleventh.

Only a hash of the key is stored. If you lose the key, generate a new one and delete the old one.

## Editing keys

The page batches edits into one **Save Changes** action. You can:

* Toggle a key **on / off** to suspend it without revoking it.
* Edit the **label** and **agent notes** in place.
* **Reorder** keys by drag — the order persists.
* **Delete** a key — this revokes it immediately and all further requests using it are rejected.

## Usage per key

Each key card surfaces:

* **Last 24h** — query count and credits charged in the last day.
* **This cycle** — query count and credits charged since the start of the current credit-billing cycle.

## Management key

In addition to the agent-scoped `sk_ah_` keys, your account has one **management key** (prefix `sk_mgmt_`) used to administer agents programmatically. Click **Rotate management key** to invalidate the old one and issue a fresh value; the new key is shown once. The masked display of the current key is always visible.

## Using a key

Pass the key as a Bearer token in the `Authorization` header of every request:

```http theme={null}
Authorization: Bearer sk_ah_...
```

For the MCP server, set the key in the server configuration. See the [OpenAI-compatible API](/openai-compatible-api) and [MCP server](/mcp-server) pages for connection details.

## Subscriber keys

Subscribers (people who log in to your agent's chat page) can generate their own API keys. Subscriber keys scope access to that user's own data and conversation history — they cannot change agent configuration or access other users' data.

Subscribers manage their own keys from the **API Keys** page in their agent dashboard (`/agent/<agent-name>/dashboard/api-keys`) — the same page and interface described here, scoped to their account rather than yours. Their chat profile page has no key-management UI, and these keys never appear in your owner dashboard.

## Examples

**Hello world — call your agent from a script.** Generate a key, then `POST` to the OpenAI-compatible endpoint with `Authorization: Bearer sk_ah_...`. You've turned your agent into an API your code can call.

**Medium — separate keys per integration.** Generate one key for your website backend, another for a Zapier automation, a third for a staging environment. Each shows its own **Usage per key**, so you can see which integration is driving traffic — and revoke just one if it's compromised, without breaking the others.

**Complex — separate owner and subscriber access.** Pair your own owner keys (which run against the agent's full configuration) with subscriber keys (each scoped to a single user's own data and conversation history) for a clean separation between "my automations" and "my users' programmatic access". Use **agent notes** on each owner key to tell the agent who or what the caller is, and **Usage per key** to attribute traffic and spend to the right integration.

## Security

* Store keys in environment variables, not in client-side code or version control.
* Generate separate keys for separate environments (development, staging, production).
* Rotate keys periodically, or immediately if you suspect a key has been compromised.

## Manage via the Management MCP

API keys can be created/listed/revoked programmatically through the [Management MCP](/manage-mcp).

|          |                                    |
| -------- | ---------------------------------- |
| Endpoint | `https://manage.agentheya.com/mcp` |
| Create   | `key.create`                       |
| List     | `key.list`                         |
| Revoke   | `key.revoke`                       |

Example:

```json theme={null}
{
  "tool": "key.create",
  "owner_id": "<your owner_id>",
  "agent_id": "<your agent_id>",
  "label": "production"
}
```

The returned `api_key` is shown only once — store it before the response is discarded. Maximum 20 active keys per agent.

> **Management key is human-admin-only.** The Management API key (`sk_mgmt_…`) that authenticates every call to this MCP can be rotated only from the dashboard by the human owner; it is not exposed to the AI Designer or the Management MCP. Rotate the management key from your dashboard while logged in as the owner.