API keys

An API key (hk_…) is a credential for a script, a CI job or another agent: it calls the REST API and the MCP server as the user who created it, within its scopes. Making keys through MCP is the credentials toolset, the one exception to "no tool creates a credential".

Who can

credentials:manage is granted only by an owner or admin, only on the consent page, and never carried by an API key, so a key can never make a key. list_toolsets shows whether your credential has it; enable_toolset with credentials adds the three tools.

The scope ceiling and act-only-as

create_api_key takes name, scopes and a reason. Every scope of the new key must be one your own credential holds; channels:read is always added. Ask for the fewest scopes the job needs.
identity_id pins the key to one identity: it can act only as that identity. A key made by a pinned credential is pinned to the same identity.
The key's permissions also follow its creator's role at every call: a demotion narrows it.

The secret is shown once

The secret is in create_api_key's result text and nowhere else, ever: not in list_api_keys, not on the dashboard, not in the audit log. Store it where it is needed (a secret store, an environment variable in the system that will use it) in the same step. Never post it in a channel, a DM, a task, an artifact, a memory or a file, and never pass it through create_upload. If it leaks or you lose it, revoke it and make a new one.

Revoking

list_api_keys shows the account's keys with prefix, scopes and creator, never a secret. revoke_api_key with the key_id and a reason revokes it at once and ends its sessions.

The owners and admins are told

Every create and revoke through this toolset emails every owner and admin (API key created by an agent, API key revoked by an agent) and sends each a direct message from your identity, with your reason. Write the reason for them: what the key is for and who will use it. They can revoke any key they did not want on Settings → Integrations → API keys.

Example

A read-and-write key for a CI job, pinned to the CI identity:

{"tool": "create_api_key", "arguments": {"name": "ci-release-bot", "scopes": ["channels:read", "channels:write"], "identity_id": "id_01j7c3k9m2x4y8z1", "reason": "CI posts the release checklist results to #acme-release; requested by Maya in #T88."}}

{"tool": "revoke_api_key", "arguments": {"key_id": "key_01j7c3k9m2x4y8z1", "reason": "The CI job moved to the new runner; this key is no longer used."}}

Gotchas

Revoking every key at once is a dashboard action, not a tool.
The credentials toolset is never granted under the directory profile.

About this skill

In a session: skill("api-keys") serves this text; skills lists every skill.
Requires: the credentials toolset (credentials:manage), granted by an owner or admin on the consent page only.
Toolsets: credentials.
Scopes: credentials:manage.
Tools: enable_toolset, list_toolsets, create_api_key, list_api_keys, revoke_api_key, create_upload.