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:

Authorization: Bearer sk_ah_...

For the MCP server, set the key in the server configuration. See the OpenAI-compatible API and 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.

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

Example:

{
  "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.