Skip to main content

Bearer keys

Authenticate non-interactive clients to a Virtual MCP (VMCP) with a long-lived credential instead of an OAuth flow. A bearer key (called an API key in the UI, sometimes a gateway key or V-MCP API key) is issued against a single Virtual MCP and lets CI jobs, scheduled automations, agent runtimes, and any other caller that can't pop a browser reach that endpoint.

For agent identities, a bearer key is one of two machine credentials. The other is an M2M token, which is the more secure of the two: the agent exchanges a client ID and secret for a short-lived access token, so the long-lived secret stays out of every MCP request and every token exchange is audited. Reach for a bearer key when the client can only send a static Authorization: Bearer header or when you want the simplest setup, and reach for an M2M token when the runtime can run a client-credentials exchange.

What a bearer key is​

Each key:

  • Is minted against one Virtual MCP and only that one, so it cannot reach any other endpoint in your organization.
  • Acts on behalf of a specific principal: either the human who created it, or an agent identity that owns the Virtual MCP.
  • Carries exactly the access policy of that principal for that Virtual MCP. It does not grant extra tools, bypass rules, or elevate permissions: if the underlying principal can't reach a tool, the key can't either.
  • Is presented as a standard bearer token on every MCP request: Authorization: Bearer <key>.

The gateway validates the key on every request: expiry, principal, Virtual MCP binding, and any server-level restrictions. Revocation takes effect immediately; there is no cached grant that outlives a deleted key.

Multiple keys per Virtual MCP​

Each Virtual MCP supports multiple keys per principal, up to a per-server limit, and each key is independently managed:

  • Name / description. A human-readable label ("ci-prod", "on-call bot", "rotation-2026-q2") that shows up in the admin UI and in audit context.
  • Optional expiry. Pick one of 1 day, 7 days, 30 days, 90 days, 1 year, or no expiry. The expiry is stored server-side; clients cannot extend it.
  • Independent revocation. Deleting one key has no effect on any other key on the same Virtual MCP.
  • One-time display. The secret is shown exactly once, in a copy-to-clipboard panel at creation. MintMCP stores only an encrypted form, so if you don't copy it then, you mint a new one.

Multiple keys are what make zero-downtime rotation possible and let a single Virtual MCP serve several environments without sharing a credential. Prefer short expiries for most automation keys and treat "no expiry" as the exception.

Lifecycle​

  1. Create. An authorized user opens the Virtual MCP's settings, clicks Create API key, sets a name and an expiry, and receives the secret in a one-time reveal panel. The key is immediately active.
  2. Distribute. Move the secret from the UI into your secret manager or CI variable store.
  3. Use. The client sends Authorization: Bearer <key> on every MCP request. No refresh, no token exchange.
  4. Observe. Every request is attributed to the key's principal in the gateway audit log.
  5. Rotate. The canonical flow is overlap, don't swap: mint a new key, roll it into the runtime, confirm traffic flows under the new key, then revoke the old one. No cutover window.
  6. Expire or revoke. At expiry or deletion, the gateway rejects further requests presented with the key.

When a key expires, the gateway returns 401 Unauthorized with WWW-Authenticate: Bearer error="invalid_token", error_description="API key has expired". That specific description lets agents and operators distinguish expiry from a bad key or the wrong Virtual MCP. Expired keys stay listed in the admin UI with an "Expired" badge for audit and cleanup, but they cannot be reactivated.

When a key is revoked, deletion is immediate. Any in-flight request that already passed auth finishes; the next call fails. There is no grace period.

Scoping​

Bearer keys are tightly scoped:

ScopeWhat it means
VMCP-boundA key issued for Virtual MCP A cannot be presented to Virtual MCP B's endpoint, even in the same organization
Principal-boundThe key acts as exactly one principal: a key minted by user Alice acts as Alice; a key minted on an agent's Virtual MCP acts as that agent. Principal identity is immutable for the key's lifetime
Policy-boundThe key inherits the Virtual MCP's tool curation, rules, and middleware. It cannot escape a rule that would otherwise block the same principal via OAuth, because it's an authentication mechanism, not an authorization override
Org-scopedKeys never cross organizations

If an automation needs to reach two Virtual MCPs, mint two keys, one per server, and configure the runtime with both. For how access policies shape what any key can reach, see Role-based access control.

Principal attribution and audit​

Every bearer-key request lands in the gateway audit log with the key's principal as the subject:

  • Human-owned keys attribute to the user who created them, so the call reads as that user rather than an interactive session.
  • Agent-owned keys attribute to the agent identity. The human admin who provisioned the key is recorded separately on the key's creation event.

Tool-call attribution keys on the principal, not the key ID: filter the audit log by principal to see what an agent or user did. The key ID lives on the key's own record, which carries a last-used timestamp, and on its creation and deletion events, so a specific credential's history is inspected there. That gives you two views: what the principal did, and when a given key was issued, last used, and revoked.

Interaction with OAuth client restriction​

MintMCP supports a per-VMCP setting, Restrict access to a specific OAuth client, that narrows which MCP client can complete OAuth against the server. This setting does not affect bearer keys. Keys have their own validation path and keep working for automation regardless of which OAuth client is registered: interactive access stays restricted while CI and agents keep working over bearer keys.

Keys and agent identities​

Virtual MCPs scoped to an agent identity rather than offered to human members use bearer keys as the simplest authentication mechanism, though M2M tokens are the more secure option when the runtime can exchange client credentials for a short-lived token. A typical agent runtime that stays on bearer keys holds a long-lived key with an explicit expiry (90 days or 1 year are common) and rotates it on a calendar cadence. Claude Tag and ChatGPT Custom GPTs using API key auth both connect this way.

Human users should prefer interactive OAuth for day-to-day use. Bearer keys for humans exist for cases where interactive auth isn't feasible: a local script, a personal automation. If you find yourself minting many long-lived human keys, move the workload to an agent identity instead: create an agent, create its Virtual MCP, and mint the key against the agent. The audit trail gets cleaner and the credential stops being tied to an employee who may one day leave.

Security guidance​

  • Prefer short expiries for CI and ephemeral automation (1–30 days). Longer expiries raise the cost of a leak.
  • Rotate aggressively using the overlap-rotate pattern. Quarterly is a reasonable floor for production agent keys.
  • Use a secret manager. Never commit keys, embed them in images, or paste them into chat.
  • Turn on SCM secret scanning so a leaked key surfaces in minutes, not months.
  • Scope at the Virtual MCP. Curate each server tightly so even a leaked key can't reach unrelated tools: least privilege at the Virtual MCP level is the main control.
  • Revoke unused keys. An unused key with an unclear owner is a dormant attack surface.
  • Never put keys in client-side code. Anything shipped to a user's machine should authenticate via OAuth.
  • Treat keys as secrets end-to-end. If a key is exposed in a log, a screen share, or a ticket, rotate it immediately.