Skip to main content

Workload identity federation

Authenticate an agent to its Virtual MCP with a short-lived OIDC token that the agent's own infrastructure mints for it, instead of a credential MintMCP issues and you store. The workload requests a token from its platform's OpenID Connect (OIDC) provider, scoped to a MintMCP audience, and sends that token as Authorization: Bearer <token> on each MCP request. MintMCP verifies the token against the provider and maps it to the agent identity you bound to it, so nothing secret has to live in the workload.

Workload identity federation applies to agent identities only, and it is available on request rather than enabled by default. Contact enterprise@mintmcp.com to turn it on for your organization.

Why workload identity over M2M​

An M2M token already keeps a long-lived secret out of the request path, but MintMCP still mints a client secret that you have to copy into each runtime's secret manager and rotate on your own schedule. Every new context (a new cluster, a new CI environment, a new service) is another secret to distribute and track.

Workload identity removes that secret. The agent's platform already gives each workload a cryptographic identity (a Kubernetes service account, a cloud instance role, a CI job identity), and its OIDC provider mints a fresh, context-specific token for that identity on demand. MintMCP trusts the provider and maps one exact identity to one agent, so there is nothing for you to store, hand off, or rotate:

  • No MintMCP-issued secret. MintMCP never generates a client secret or key for this path, so there is no one-time secret to capture and no secret to leak.
  • Tokens mint themselves per context. Each workload gets its own short-lived token from its own infrastructure, instead of you provisioning and placing a client secret for every context by hand.
  • Rotation is the provider's job. Signing keys rotate through the provider's published key set (JWKS), and MintMCP follows the rotation with no action on your side.
  • Revoke at the source. Removing the workload upstream (deleting the service account or role) stops it from getting new tokens, and disabling the binding or provider in MintMCP cuts it off on the next request.

Reach for M2M tokens when the runtime has no workload identity to present and can run a client-credentials exchange, and for a bearer key when the client can only send a static header.

PropertyBearer keyM2M tokenWorkload identity
What each request carriesThe long-lived secretA short-lived access tokenA short-lived OIDC token from your provider
MintMCP-issued secretThe key itselfA client secret you storeNone
Who mints the credentialMintMCPMintMCP mints the client; your runtime exchanges the secretYour OIDC provider, per workload
RotationRe-mint the key, delete the old oneRotate the client secret on your scheduleYour provider rotates signing keys; MintMCP follows
ContainmentRevoke the keyToken expires, or revoke a secretToken expires, disable the binding or provider, or remove the workload upstream

How it works​

Trust is split into two configuration surfaces so that establishing which issuers your organization trusts is a separate decision from assigning an identity to an agent:

  1. An organization admin registers a workload identity provider once per external issuer.
  2. An agent admin binds one exact subject from an approved provider to an agent identity.

Register a workload identity provider​

In enterprise settings, open Workload identity providers and create a provider with a name and the exact issuer URL of your OIDC provider. MintMCP runs OIDC discovery against the issuer, validates its published signing keys, and stores the trust configuration. The issuer must be reachable over public HTTPS so MintMCP can fetch its discovery and JWKS documents.

Each provider shows the canonical audience your workloads must request, derived from your deployment's application URL:

https://app.mintmcp.com/oidc/workload   # US
https://eu.mintmcp.com/oidc/workload    # EU

Copy the audience shown for your provider rather than composing it by hand, and configure your workload to request a token for that exact value. Registering a provider is org-wide: disabling it is an immediate emergency stop for every agent bound to it, so provider management can require a stronger permission than assigning a subject to an agent.

Bind a subject to an agent identity​

Open the agent Virtual MCP's authentication settings and, in the Workload identity card, select an approved provider and enter the exact sub value your provider puts in the workload's token. MintMCP maps that one subject to this agent identity. The match is exact and case-sensitive, and each agent accepts one binding at a time, so you have a single external identity to reason about per agent. Changing the provider or subject means deleting the binding and creating its replacement.

No token or key is ever entered here: the card only names an already-trusted provider and the subject to expect.

How a request authenticates​

At request time the workload presents a token it minted itself, and MintMCP verifies it and resolves the bound agent before the call reaches any connector:

The external token proves which workload is calling; it does not carry MintMCP permissions. After MintMCP maps the verified subject to the agent identity, the request uses that agent's own connector credentials, exactly as any other agent traffic does. Claims such as roles, groups, or scopes in the external token are ignored and never grant access.

Scoping​

A workload token carries the same tight scope as any agent credential, with trust anchored to the approved provider:

ScopeWhat it means
Provider-trustedOnly tokens from an approved organization provider, matching its exact issuer and audience, are considered
Subject-boundOne exact, case-sensitive subject maps to exactly one agent identity
VMCP-boundThe token authenticates against that agent's Virtual MCP; the gateway rechecks the agent and organization on every request
Principal-boundThe token acts as exactly one agent identity, never a human user, and external claims never elevate it
Policy-boundThe token inherits the Virtual MCP's tool curation, rules, and middleware
Org-scopedTokens never cross organizations; the organization comes from the target Virtual MCP, never from the token

For how access policies shape what any agent credential can reach, see role-based access control.

Audit​

Workload authentication is auditable at both configuration and request time:

  • Provider lifecycle is recorded in signed provider history: created, updated, enabled or disabled, metadata refreshed, and deleted transitions, each with the acting admin.
  • Binding lifecycle writes discrete events: agent_workload_identity_binding_created, agent_workload_identity_binding_updated, and agent_workload_identity_binding_deleted, each recording the agent, provider, subject, and acting admin.
  • Runtime authentication emits structured logs and metrics under the oidc_workload method (issuer and subject resolution, key cache activity, and a bounded result reason), so operators can see authentication outcomes without a durable audit row per MCP call.
  • Tool calls made with a workload token attribute to the agent identity, the same as any other agent traffic, so agent activity stays distinguishable from human activity in the gateway audit log.

Tokens, full token claims, signatures, and signing-key material are never stored or logged. For where these land in your audit pipeline, see audit and observability.

Constraints​

  • Token claims. MintMCP accepts a compact, signed JWT whose iss exactly matches the provider's issuer, whose sub exactly and case-sensitively matches the bound subject, and whose aud contains the canonical MintMCP audience. Tokens must carry iat and exp and may live at most one hour. Signing algorithms are asymmetric only: RS256, PS256, ES256, and EdDSA. Unsigned (none) and symmetric (HS*) tokens are rejected.
  • Trust is configured on the provider side. MintMCP verifies tokens but never issues them. Your OIDC provider must be reachable over public HTTPS for discovery and key rotation, and you configure the workload to request the MintMCP audience. Establishing which issuers to trust happens in provider settings; agents only reference an already-approved provider.
  • One binding per agent. An agent accepts a single external identity at a time. Supporting a workload from a different provider or subject means replacing the binding.
  • Kubernetes uses projected service account tokens. Configure a service account token volume projection with the MintMCP audience and bind that service account's subject to the agent. MintMCP consumes the standard projected OIDC token; it does not use SPIFFE JWT-SVID.
  • Configured in the web UI only. Providers and bindings are managed in enterprise settings and agent Virtual MCP settings, not through the Admin MCP.