Workload Identity Federation - TrueFoundry Docs

Workload Identity Federation lets your workloads authenticate to TrueFoundry with short-lived tokens from an identity provider you already operate — Kubernetes, GitHub Actions, AWS, or GCP — instead of long-lived Virtual Account tokens (VATs). The workload presents a signed JWT from that provider. TrueFoundry validates it against an Identity Provider and Claims (or Subject) mapping you configure, then returns a short-lived TrueFoundry access token bound to a Virtual Account or Agent. There is no static TrueFoundry secret to mint, store in CI, rotate, or leak. This is inbound federation into TrueFoundry (workload → TrueFoundry). It is not Workforce SSO, and not outbound cloud WIF used when TrueFoundry calls Vertex or other model providers.

For Okta, Entra, Auth0, and custom IdPs that send a JWT as Bearer on every API call, see External JWT. Workload providers use token exchange — do not send the platform JWT as Bearer on every TrueFoundry call. For a comparison of both paths, see the Identity Providers overview.

Concepts

You configure three things before a workload can federate:

Identity Provider — registers the external issuer TrueFoundry should trust (issuer, audiences, JWKS URI, and the lifetime of the TrueFoundry token returned by exchange).
Mapping — which claims on the JWT must match. On a Virtual Account this is Claims; on an Agent this is Subject.
Principal — the Virtual Account or Agent the exchanged token acts as. Permissions stay on that principal; exchange never creates a new account.

Together they mean: tokens signed by issuer X, with claims that look like Y, may act as Virtual Account or Agent Z. Teams are not supported as Workload Identity principals.

How it works

Your platform issues a JWT to the workload (Kubernetes projected service-account token, GitHub Actions OIDC token, AWS STS / outbound federation JWT, or GCP workload token).
The workload exchanges that JWT at the TrueFoundry token endpoint.
TrueFoundry verifies the signature and issuer/audience, matches Claims or Subject on the named Virtual Account or Agent, and returns a short-lived TrueFoundry access token.
The workload calls the AI Gateway or APIs with Authorization: Bearer <access_token>, then exchanges again before expiry. There is no refresh token.

Provider guides

Choose the guide for the environment that issues the workload JWT:

GitHub Actions

CI OIDC tokens from token.actions.githubusercontent.com.

Kubernetes

Projected service-account tokens; match namespace and service account.

AWS

IAM outbound web identity (GetWebIdentityToken) or EKS via Kubernetes.

GCP

Google identity tokens or GKE; match sub and email.

Set up federation

Go to Settings > Security & Access > Identity Providers and add a provider. Choose Kubernetes, GitHub, AWS, or GCP.

Field	Required	Description
Provider Name	Yes	Unique ID (3–32 chars: lowercase, numbers, hyphens; start with a letter; end with a letter or number).
Issuer URL	Yes	Must exactly match the JWT `iss` claim.
Allowed Audiences	Yes	At least one JWT `aud` value must intersect this list (string or array `aud`).
JWKS URI	Yes	Public HTTPS JWKS URL reachable from the control plane.
Token TTL (seconds)	No	Lifetime of the exchanged TrueFoundry token (`60`–`3600`, default `3600`).

Workload providers do not include Resolve Token To. Exchange the platform JWT; do not send it as Bearer on every call. Provider-specific issuer, JWKS, and claim examples are in the provider guides.

Map a Virtual Account or Agent

Create or select a Virtual Account (or Agent) and grant it the permissions the workload needs. Then add an Identity Provider Mapping for the workload provider:

Virtual Account — use Claims (not a single Claim Value).
Agent — use Subject (subject key / subject value). YAML still uses the claims key.

Required keys depend on the provider:

Provider	Required keys
`kubernetes`	`kubernetes.io/namespace`, `kubernetes.io/serviceaccount/name`
`github`	`repository`
`aws`	`sub`
`gcp`	`sub`, `email`

Paths use / as a nested-object separator when reading the JWT. The dot in names such as kubernetes.io is part of the key, not a path separator. Values must not contain whitespace. You can add more claim matches beyond the required keys.Full examples: GitHub Actions, Kubernetes, AWS, GCP. Also see Identity provider mappings and Agent Registry.

Exchange the platform JWT

Obtain the platform JWT, then call the token endpoint. No client_id and no Authorization header on this grant.Prefer the token_endpoint from OpenID discovery:GET https://<tenant-host-origin>/<tenant>/.well-known/openid-configurationThe worked path is /{tenant}/oauth2/v1/token on the tenant-host origin — same shape as OIDC discovery / issuer (no /api/svc prefix). SaaS: https://<tenant>.<your-tenant-base-domain>. Dedicated: the origin of your public control-plane URL (strip any /api/svc path if present); on dedicated installs that origin is often the same host you use for ordinary APIs, but the exchange path itself never includes /api/svc.

curl -sS "https://<tenant-host-origin>/<tenant>/oauth2/v1/token" \
  -H 'Content-Type: application/json' \
  -d "{
    \"grant_type\": \"urn:ietf:params:oauth:grant-type:token-exchange\",
    \"subject_token\": \"$WORKLOAD_JWT\",
    \"subject_token_type\": \"urn:ietf:params:oauth:token-type:jwt\",
    \"tfy_subject\": \"virtual_account:<virtual-account-name>\"
  }"

tfy_subject is virtual_account:<name> or agent:<name>.Successful response:

{
  "token_type": "Bearer",
  "access_token": "<truefoundry-jwt>",
  "expires_in": 900,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

expires_in matches the provider’s Token TTL (or 3600 if unset). Re-exchange before expiry — there is no refresh token.Python example:

import os
import requests

CONTROL_PLANE = os.environ["TFY_CONTROL_PLANE"]  # tenant-host origin only, no /api/svc path
# SaaS example: https://<tenant>.truefoundry.cloud  |  dedicated: origin of public CP URL
TENANT = os.environ["TFY_TENANT"]
SUBJECT_TOKEN = os.environ["WORKLOAD_JWT"]  # platform-issued JWT
TFY_SUBJECT = "virtual_account:builder"

response = requests.post(
    f"{CONTROL_PLANE}/{TENANT}/oauth2/v1/token",
    json={
        "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
        "subject_token": SUBJECT_TOKEN,
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "tfy_subject": TFY_SUBJECT,
    },
    timeout=30,
)
response.raise_for_status()
access_token = response.json()["access_token"]

# Use like a VAT: Authorization: Bearer <access_token>

Call TrueFoundry with the access token

Pass Authorization: Bearer <access_token> to the AI Gateway, MCP Gateway, REST API, or SDK the same way you would a VAT.

Troubleshooting

Exchange returns invalid_grant

TrueFoundry returns an opaque error when verification or claim matching fails. Check that:

The JWT iss matches the IdP issuer.
The JWT aud intersects the IdP allowed audiences.
Exactly one mapped Identity Provider matches the JWT issuer and audience. If the Virtual Account or Agent lists the same workload IdP more than once, exchange fails even when only one Claims / Subject set would fit. After that unique IdP row is chosen, every saved Claims / Subject entry must equal the JWT.
Prefer a single mapping row per workload IdP on a given Virtual Account or Agent; put distinct claim sets on different principals when you need them.
Every required Claims / Subject entry matches the JWT.
tfy_subject names an existing Virtual Account or Agent that maps this provider.
The subject JWT header includes a non-empty kid that exists on the provider JWKS.

Exchange returns unsupported_grant_type

If exchange returns unsupported_grant_type, the workload identity grant is not enabled on this control plane — contact your TrueFoundry admin or support.

Exchange returns server_error

If exchange returns server_error with “Workload identity keys are not available,” the control-plane auth cache is disabled or not ready — retry after it is healthy, or escalate to TrueFoundry admin / support.

Direct Bearer with the platform JWT fails

That path is not supported for kubernetes, github, aws, or gcp. Exchange first, then call APIs with the TrueFoundry access token.

GitHub Actions · Kubernetes · AWS · GCP
External JWT — direct Bearer with an IdP JWT
Identity Providers overview
Manage Virtual Accounts — Claim value vs Claims
Agent Registry — Subject vs Claims for Agents
API Keys — PATs and VATs when federation is not in use

​Concepts

​How it works

​Provider guides

GitHub Actions

Kubernetes

AWS

GCP

​Set up federation

​Troubleshooting

​Related

Concepts

How it works

Provider guides

Set up federation

Troubleshooting

Related