Skip to content

Agent API Keys

Agent API keys are how external tools authenticate to Mention. Every API key belongs to an Agent, which is in turn scoped to one or more Audiences. This page is the developer-side reference for using keys; for the admin-side flow of creating and managing them, see Agents.

Key format

Agent API keys are prefixed with mk_, followed by an encoded, signed payload (it looks like mk_<encoded-payload>.<signature>, not a fixed-length string). Treat the whole thing as a secret — anyone with the key can read every Audience the Agent has been granted.

A key is shown once at creation (and again on rotation), alongside a ready-to-paste MCP config snippet. After that the full key is no longer retrievable. If you lose a key, the admin must rotate it to issue a new one.

Using a key

The MCP server and the underlying API both authenticate via Bearer token in the Authorization header:

Authorization: Bearer mk_…

Most MCP clients (Claude Desktop, IDE extensions) take a header configuration where you can set this directly. For the underlying HTTP API, send the header with each request.

Scope

An Agent can only access content from Audiences it has been granted. If you call a tool with an audience_id the Agent does not have a grant for, the call is rejected.

To widen access, an admin adds Audience grants from the Agent's detail view in the Mention admin UI. To narrow access, the admin removes grants. There is no per-tool or per-Concept scoping — access is at the Audience level.

Rotation

Rotate a key when:

  • It may have been exposed (committed to a repo, leaked in a log, shared with a vendor that no longer needs access).
  • A team member with access to the key leaves the team.
  • You want to cycle credentials on a regular cadence.

Rotation immediately invalidates the old key and issues a new one. Any client still using the old key will start getting 401 responses. Update your clients with the new key as part of the rotation procedure.

Revocation

To revoke a key without issuing a replacement, an admin can either:

  • Delete the Agent — removes the Agent and all of its Audience grants. The key stops working immediately.
  • Remove the Audience grant — the key still works but can no longer access that Audience.

There is no separate "disable key" toggle; rotate or delete depending on whether you want to issue a replacement.

Storing keys

Treat Agent API keys like any other production secret:

  • Store them in a secret manager (1Password, AWS Secrets Manager, GitHub Actions secrets, etc.).
  • Inject them at runtime as environment variables; do not commit them to source control.
  • Use distinct Agents per consumer where it makes sense — that way rotating one consumer's key does not affect others.