Skip to content
Status

Identity / Workload identity

Workload identity

Let CI jobs, Kubernetes pods, Claude Tag channels, and other workloads connect as an agent by exchanging the identity token their own platform issues, with no stored secret. Set up trusted platforms and access rules while registering the agent.

Workload identity lets a CI job, Kubernetes pod, Claude Tag channel, or other workload connect to MCP servers without a stored secret. The workload presents the identity token its own platform already issues, such as a GitHub Actions OIDC token, and exchanges it for a short-lived Speakeasy access token. The workload then acts as the agent assigned to it and inherits that agent’s policy in full.

Viewing trusted platforms and access rules requires workload:read, and changing them requires workload:write. Only the Admin role holds both by default. A rule hands a machine everything its agent can do, so grant workload:write only to people trusted with that.

Choose the credential that fits where the agent runs:

API keyWorkload identity
Runs inAny runtimeRuntimes whose platform issues identity tokens, such as Claude Tag, GitHub Actions, Kubernetes, and SPIFFE
Secret to storeYes, the keyNone
Token lifetimeUp to one year, revocable15 minutes, with no refresh token
Servers with per-user OAuthThe key owner’s connected accountThe agent owner’s connected account

Workload identity removes the risk of a leaked long-lived key. Use an API key for laptops, hosted agents, and any runtime without a platform identity token.

Three pieces of configuration decide whether a workload gets in and what it can do:

  • Trusted platform: an issuer whose tokens Speakeasy verifies, identified by its issuer URL and the URL of its signing keys (JWKS URI). Trusting a platform admits nothing on its own.
  • Access rule: a token subject, the sub claim, that is allowed to sign in, and the agent it acts as. A rule matches one subject exactly, or every subject that starts with a prefix when it ends in *.
  • Agent: supplies the whole policy the workload acts under. The workload holds no permissions of its own, and it can reach only what both the agent’s policy and the agent owner’s current permissions allow. If the owner loses access to a server, the workload loses it on its next request.

A workload is admitted only when its token is signed by a trusted platform and its subject matches an access rule under that platform. Platforms such as Anthropic, GitHub, and Google sign tokens for all of their customers, so a valid signature alone proves nothing. The access rule is the security boundary.

The workload sends its platform token to the token endpoint of a Speakeasy authorization server and receives an access token valid for 15 minutes. It sends that access token as a bearer token on MCP requests. There’s no refresh token: when the access token expires, the workload exchanges a fresh platform token.

Trust and access rules are set up on the agent the workload acts as. Edit can’t add them to an existing agent, so create a new agent for the workload. Trust applies to MCP servers in every project. Open Identity > Agents, select New agent identity, and on the Agent sign-in step choose one of two kinds of platform:

  • A card for a platform Speakeasy has verified, with its issuer and signing keys already filled in. The setup asks only for what differs per organization. To connect Claude Tag, follow Set up Claude Tag with workload identity. To connect a GKE cluster, follow Connect GKE workloads with workload identity. To run Claude Code or Codex in GitHub Actions jobs as the agent, follow Connect GitHub Actions jobs with workload identity. Kubernetes, SPIFFE, and Google Cloud are listed as coming soon and can’t be chosen yet.
  • Custom OIDC issuer, under Advanced: trust another platform’s tokens, for any other platform that already signs OIDC tokens for its workloads, such as a CI provider, a cluster, or your own identity service.

Choose Custom OIDC issuer. On Identity provider, fill in:

  • Name: what the platform is called in Speakeasy. Not used for matching.
  • Issuer URL: the iss claim its tokens carry, exactly. It must be an HTTPS URL, and Speakeasy stores it as entered, so copy it from the platform’s documentation or discovery document.
  • JWKS URL: where the platform publishes the keys its tokens are signed with. It must be an HTTPS URL.

On Which workloads, fill in:

  • Subject: the sub claim to accept, compared exactly as entered.
  • Match: This subject only, or any subject under a prefix. A prefix admits every workload beneath it, so end it where the platform’s own separator falls.

Nothing is created until Connect platform on that step. Trusting the platform and allowing its access are both recorded in the organization audit log. Point it at Speakeasy then shows the issuer URL and token endpoint to configure in the platform, and Check it worked waits for the first exchange.

The issuer is fixed once trusted. To trust a different issuer, set it up as a new platform.

For a worked example from start to finish, using a Vercel Function, follow Connect any OIDC platform with workload identity.

Use a wildcard only where the platform controls the varying part

A rule ending in * admits every subject that starts with the text before it, including subjects created later. That’s safe when the platform mints the varying part, as Anthropic does with agent IDs in wimse://identity.anthropic.com/org/ORG_ID/agent/*. It isn’t safe when the caller influences the subject. For example, repo:acme/deploy:* on GitHub Actions admits every branch, so anyone who can push a branch gets in.

A rule for an exact subject takes priority over a wildcard rule that also matches it, and a longer wildcard takes priority over a shorter one. This makes it possible to admit a whole fleet under one agent and give a single workload a different one.

The Credentials section of an agent lists the platforms that sign in as it, under Federated access. Select Remove on a platform to stop it signing in as that agent. The subject is fixed once allowed, so admitting a different one means setting it up again.

Removing access doesn’t end sessions already issued. To stop a workload immediately, also revoke its sessions on MCP Sessions, or suspend the agent. Every change to platforms and access rules is recorded in Audit Logs.

A workload exchanges its token at the token endpoint of a shared Speakeasy authorization server, which serves every MCP server attached to it. The setup shows the issuer URL and token endpoint to use on its Point it at Speakeasy step. Organization admins can also find them under Speakeasy Authorization Servers in the organization settings.

Workload sign-in needs an authorization server in shared mode. If none is listed, contact Speakeasy to enable one for the organization or a project.

Put every server the workload calls on the same authorization server

An access token from a shared authorization server works only at MCP servers that sign clients in through it. A server with its own per-server sign-in, or one on another shared authorization server, answers 401 with expired or invalid access token, even though the exchange succeeded. Check each server’s User session issuer under Settings > Authentication: it must be the shared authorization server whose token endpoint the workload uses.

Request a token from the platform with its audience set to the authorization server’s issuer URL. Then post it to the token endpoint using the OAuth JWT bearer grant:

Terminal window
curl https://AUTHENTICATION_HOST/oauth/usi/ISSUER_ID/token \
--data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
--data-urlencode "assertion=$PLATFORM_TOKEN" \
--data-urlencode "resource=https://MCP_HOST/mcp/SERVER_SLUG"

No client ID or secret is involved. The resource parameter is optional:

  • With resource, the access token works only at that MCP server.
  • Without it, the access token works at every MCP server of the authorization server that the agent may connect to.

A successful exchange returns the access token:

{
"access_token": "eyJ...",
"token_type": "Bearer",
"expires_in": 900
}

Send it as Authorization: Bearer ACCESS_TOKEN on MCP requests. When it expires or is revoked, the MCP server answers 401 with error="invalid_token", and the workload exchanges a fresh platform token. A 401 on the first request after a successful exchange usually means the server isn’t on this authorization server. Use a new platform token for each exchange, because a token with a jti claim is accepted only once.

Every refusal returns the same invalid_grant error, so callers can’t probe the trust policy. A resource that isn’t an MCP server of the authorization server returns invalid_target.

Some MCP servers call an upstream service with each person’s own connected account. A workload has no person behind it, so it uses the account connected by the owner of its assigned agent. If the owner hasn’t connected an account for that service, calls to the server fail rather than fall back to another credential.