# Worked example of IdP token authentication

> End to end, through the management API: register an organization's identity provider as a trusted issuer on a gateway, bind it to one project, and call the gateway with a client-credentials token instead of an API key.

Enterprise Tier

This example takes one application from a client registered in the organization's own <Term id="identity-provider-idp">identity provider</Term> to a successful request on a <Term id="data-plane">data plane</Term>, with no Agent Router API key handed out. Every step is a management API call. The token path is described in <Link to="/agent-router-enterprise/guides/operate-and-govern/project-and-data-plane-management/authenticate-gateway-requests/">Authenticate gateway requests with an external IdP</Link>; this page applies it to one PingFederate client and shows the token at each stage.

{/* TODO(#316): the claim names and values below are neutral examples in the shape proposed upstream. Replace them with the customer-confirmed entitlement claim, sample token, and environment claim when they are confirmed. */}

:::info[Preview]
Authenticating with an identity-provider token is a preview from 0.7.0. Its limits are listed at the top of [Authenticate gateway requests with an external IdP](/agent-router-enterprise/guides/operate-and-govern/project-and-data-plane-management/authenticate-gateway-requests/).
:::

## The example

One application, a payments assistant, runs in the non-production environment and calls one Agent Router project. The values used throughout:

| Item | Value in this example |
| :---- | :---- |
| Identity provider | PingFederate, issuer `https://idp.example.com` |
| Signing keys | `https://idp.example.com/pf/JWKS` |
| OAuth client | `payments-assist-nonprod`, client-credentials grant |
| Audience | `api://agent-router-nonprod` |
| Scopes the client is granted | `aigw.invoke.nonprod` and `aigw.profile.payments-assist.nonprod` |
| Environment claim | `deployment_env`, value `nonprod` |
| Organization (customer ID) | `acme` |
| Project | `payments-assist` |
| Gateway | slug `gw-nonprod`, environment `nonprod` |

The management API calls use `https://management.example.com` for the management API host and `${ADMIN_API_KEY}` for a management key with the `admin` scope, sent as a Bearer token.

## Prerequisites

- Every data plane serving the project runs 0.7.0 or later, and the management plane was upgraded before them (see [Upgrading a data plane that carries a policy](/agent-router-enterprise/guides/operate-and-govern/project-and-data-plane-management/authenticate-gateway-requests/#upgrading-a-data-plane-that-carries-a-policy)).
- The project exists and is attached to the gateway; see [Serve a project from a data plane](/agent-router-enterprise/self-hosted-data-plane/projects-and-hostnames/serve-a-project-from-a-data-plane/). The gateway's UUID is needed for two of the calls below and its slug for one.
- At least one model is assigned to the project.
- The identity provider's discovery document and key set are served from a public hostname. A `jwks_uri` that resolves to an internal address is refused when the policy is written.

## Step 1: shape the token in the identity provider

The gateway reads five things from the token. Each one is set on the identity provider's side, per client, before anything is configured in Agent Router.

| Claim | Required form | Set in PingFederate by |
| :---- | :---- | :---- |
| `iss` | Exactly the issuer registered in Step 3 | The base URL of the server |
| `aud` | Contains the audience registered in Step 3 | The **Audience Claim Value** of the JWT access token manager the client is restricted to |
| `scope` | Contains every required scope, as a space-delimited string | **Scope Claim Name** `scope` with **Space Delimit Scope Values** on |
| `client_id` | A stable identifier for the application | **Client ID Claim Name** `client_id` |
| `deployment_env` | The environment the token was issued for | An attribute mapped to a fixed value on the environment's access token manager |

The audience is fixed per client in the identity provider, and the client cannot ask for a different one. PingFederate refuses a token request carrying `resource=` with `invalid_target` and ignores `audience=`; Keycloak ignores both and always issues the audience its audience mapper sets. A token with the wrong audience is fixed by the identity provider administrator, not by the application.

A token issued to this client, decoded:

```json
{
  "alg": "RS256",
  "kid": "agent-router-rs-1_RS256"
}
```

```json
{
  "iss": "https://idp.example.com",
  "aud": "api://agent-router-nonprod",
  "sub": "payments-assist-nonprod",
  "client_id": "payments-assist-nonprod",
  "scope": "aigw.invoke.nonprod aigw.profile.payments-assist.nonprod",
  "deployment_env": "nonprod",
  "iat": 1791208798,
  "exp": 1791209098,
  "jti": "zAsnZbEAtjtEIl9ANgrslA"
}
```

The shape is what PingFederate 13.1 issues for a client-credentials grant. Keycloak issues the same claims with two differences that do not matter to the gateway: its `iss` ends in `/realms/<realm>`, and its `sub` is the service account's UUID rather than the client ID, so the identity rule in Step 4 names `client_id`, which both providers carry.

## Step 2: declare the gateway's environment

The gateway compares the token's environment claim against the environment the gateway declares, so the gateway declares one first. Only a platform administrator can set it. The value matches `^[A-Za-z0-9][A-Za-z0-9._-]{0,62}$` and is compared exactly, case included.

```bash
curl -sS -X PATCH "https://management.example.com/admin/v1/project-gateways/${GATEWAY_UUID}" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"environment": "nonprod"}'
```

Skip this step and leave `environmentClaim` out of Step 3 where a separate issuer or audience per environment already keeps production and non-production tokens apart.

## Step 3: register the issuer for the project

A gateway auth policy registers one issuer for one project on one gateway. The call names the gateway by its slug.

```bash
curl -sS -X POST "https://management.example.com/admin/v1/gateway-auth-policies" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "acme",
    "projectId": "payments-assist",
    "projectGatewayId": "gw-nonprod",
    "name": "pingfederate-nonprod",
    "mechanism": "jwt",
    "issuer": "https://idp.example.com",
    "jwksUri": "https://idp.example.com/pf/JWKS",
    "audiences": ["api://agent-router-nonprod"],
    "requiredScopes": ["aigw.invoke.nonprod", "aigw.profile.payments-assist.nonprod"],
    "environmentClaim": "deployment_env"
  }'
```

The response carries the policy's `id`, which Step 4 needs. A policy is enabled unless `"enabled": false` is sent.

- **`audiences`** must name at least one audience from 0.11.0, so a `jwt` policy created without one is refused.
- **`requiredScopes`** is the entitlement check. The gateway reads `scope` and `scp`, splits a string on spaces, and requires every listed scope to be present, compared case-sensitively. Scopes the token carries beyond the list are ignored, and their order does not matter. A token whose `scope` is present but empty is refused with `missing_scope`.
- **`environmentClaim`** names the claim, not its value. The value the claim must carry is the gateway's environment from Step 2. An enabled policy naming an environment claim is refused while the gateway declares no environment.
- **No `extractionHeader`** is set, so the token can be sent as `Authorization: Bearer` or in `x-tars-idp-token`.

## Step 4: say which claim identifies the application

An identity mapping rule tells the gateway which claim names the application, and whether an application it has not seen before is admitted. This rule admits any client whose `client_id` starts with `payments-`, creating its identity on the first call, up to 20 applications:

```bash
curl -sS -X POST "https://management.example.com/admin/v1/gateway-auth-policies/${POLICY_ID}/rules" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "claimName": "client_id",
    "claimValueTemplate": "payments-*",
    "target": "jit",
    "jitProjectId": "payments-assist",
    "jitPrincipalCap": 20
  }'
```

`claimValueTemplate` is a shell-style pattern: `*` matches any run of characters except `/`, `?` matches one character, and an empty template matches every value on a `pre_registered` rule. Only a claim with a string value matches. From 0.11.0 a `jit` rule must set `claimValueTemplate` or `matchEveryClaimValue: true`, but not both, and an empty template is refused on a `jit` rule, so a rule meant to admit every value says so with `matchEveryClaimValue`. A `jit` rule that sets no `jitPrincipalCap` creates no further application once the project holds 100 external applications. Rules are tried in the order they were created, and the first match applies. A `pre_registered` rule instead admits only applications registered in advance, and refuses an unknown one with `identity_not_registered`.

## Step 5: let the project accept tokens

The project's membership of the gateway still accepts API keys only. Switching it to accept both keeps existing API-key callers working while the token path is proven:

```bash
curl -sS -X PATCH "https://management.example.com/admin/v1/project-gateways/${GATEWAY_UUID}/projects/payments-assist" \
  -H "Authorization: Bearer ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"acceptedCredentials": "ACCEPTED_CREDENTIALS_BOTH"}'
```

`ACCEPTED_CREDENTIALS_TOKEN` refuses API keys for the project from then on. Either value is refused unless the project holds an enabled policy on that gateway, which is why Step 3 comes first.

## Step 6: get a token and call the gateway

The application obtains a token from the identity provider with the client-credentials grant. The test client in this example authenticates to PingFederate with a signed client assertion (`private_key_jwt`); a client secret works the same way where the identity provider allows it.

```bash
curl -sS -X POST "https://idp.example.com/as/token.oauth2" \
  -d grant_type=client_credentials \
  -d client_id=payments-assist-nonprod \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="${CLIENT_ASSERTION}" \
  --data-urlencode "scope=aigw.invoke.nonprod aigw.profile.payments-assist.nonprod"
```

The response's `access_token` is sent to the gateway with the project header, on the same base URL and endpoints an API-key caller uses:

```bash
curl -sS "https://gw-nonprod.example.com/v1/chat/completions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-tars-project: payments-assist" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hello"}]}'
```

From 0.12.0 a request that carries an identity provider token in `Authorization: Bearer` and the same token once in `X-API-Key` is served as a token call, which is how Claude Code sends the output of its `apiKeyHelper`. See [Connect Claude Code](/agent-router-service/guides/coding-agents/claude-code/connect/#option-c-identity-provider). A single whitespace-only `X-API-Key` beside a token is treated as absent. Every other `X-API-Key` beside a token is refused with `400` `credentials_conflict`, as before. Sending `X-API-Key` more than once beside a token is deprecated: when the first value is empty, the data plane still serves the request as a token call and ignores the later values, and a later release refuses such a request with `400` `credentials_conflict`. At most one `X-API-Key` is sent beside a token, either the same token as in `Authorization` or none.

A `200` is the end of the example. On that first call the gateway created the application's identity and one API key for it, named `https://idp.example.com#client_id=payments-assist-nonprod`. Later calls with a token for the same client reuse it, and request logs and usage are attributed to that key. The data plane removes the token and the project header before the request reaches the model provider.

## How the token is bound to the project

In this example the project is the one the `x-tars-project` header names, and the header is a request, not a grant. The data plane admits the token for that project only when all of these hold:

1. The gateway serves the project, and the project's membership accepts tokens (Step 5).
1. The project holds an enabled policy on this gateway for the token's issuer (Step 3). A policy for the same issuer held by another project does not count.
1. The token verifies against that policy's keys, audience, and expiry, carries every required scope, and carries the gateway's environment.
1. A rule of that policy matches the token, and a `jit` rule matches only for the project it names (Step 4).

The scope in Step 3 is what turns "the organization trusts this identity provider" into "this application may use this project": a client the identity provider has not granted `aigw.profile.payments-assist.nonprod` is refused, even though its token is otherwise valid.

One gateway takes at most one enabled policy per issuer across every project it serves, so on one gateway a call that names its project reaches only the project that holds that issuer's policy there. A token that carries profile scopes for several projects is held to that one project on a given gateway, and the other profile scopes are ignored there.

From data plane 0.10.0 the application can leave out `x-tars-project` once a platform administrator binds one of its token's claim values, such as `client_id` set to `payments-assist-nonprod`, to a project on the issuer's policy. The data plane then takes the project from the one binding that matches the token. The bound project does not have to hold the issuer's policy itself: the gateway's one policy for the issuer verifies the token, and one of its rules has to cover the bound project. A call that sends the header never reads a binding, and is held to the conditions above. Writing a binding, and the refusals a call without the header can meet, are in [Calls without the project header](/agent-router-enterprise/guides/operate-and-govern/project-and-data-plane-management/authenticate-gateway-requests/#calls-without-the-project-header).

## Attribution headers are caller-asserted {#attribution-headers}

An application often sends headers that describe its own call, such as the end user it acts for, the agent making the call, and that agent's version. Agent Router defines no names for these. The names below are examples:

```bash
curl -sS "https://gw-nonprod.example.com/v1/chat/completions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "x-tars-project: payments-assist" \
  -H "x-end-user: u-48213" \
  -H "x-agent-id: invoice-triage" \
  -H "x-agent-version: 2.3.1" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hello"}]}'
```

- **They reach the model provider unchanged.** On a token call, as on an API-key call and on the passthrough path, the data plane removes only the headers that the gateway alone writes, listed in [Headers removed from every request](/reference/gateway-behavior/#stripped-headers), along with the token itself and the project header. Every other header passes through. A name that starts with one of the gateway's own prefixes, such as `x-tars-rl-`, `x-ai-eg-`, or `x-internal-traces-`, is removed, so attribution headers use names outside those families. From data plane 0.10.0, every `x-tars-*` and `x-router-*` header and `x-project-id` are also removed before the request reaches the model provider, including ones the application set itself.
- **They are never authorization input.** The gateway checks no header a caller adds against the token. Any application holding a valid token can send any value, and none of these headers decides the project, the models, the budget, or the rate limit that applies. Those come from the token, the gateway auth policy, and the project, as described above.
- **They are recorded for attribution.** Under the **Full** request log mode, the record's `request_headers` carries them. A name that starts with `x-tars-` is kept there only when it is listed in `REQUEST_LOG_EXPORT_HEADERS` on a 0.9.0 or later data plane. Under **Metadata only**, request headers are not sent to the management plane at all. See [Can an application's own `x-tars-` headers be kept in the request log?](/agent-router-enterprise/guides/operate-and-govern/compliance-and-governance/control-request-log-data/#can-an-applications-own-x-tars--headers-be-kept-in-the-request-log)

Because the values are whatever the caller sent, a report that groups usage by them shows what each application claims about its callers, not an identity the gateway verified. Usage that has to be tied to a verified identity is grouped by the application's API key instead.

## When a step is wrong

Each refusal names its cause in the error body's `code`. The body follows the gateway's [error format](/reference/gateway-behavior/#error-response-format), and the `X-Request-ID` response header identifies the request:

```json
{
  "error": {
    "message": "The IdP token lacks a scope the gateway requires.",
    "type": "authorization_error",
    "param": null,
    "code": "missing_scope"
  }
}
```

| Status | `code` | Step to revisit |
| :---- | :---- | :---- |
| `400` | `missing_project` | Step 6: the request carries a token and no `x-tars-project` header, and the issuer's policy holds no claim-to-project binding |
| `403` | `no_project_binding`, `ambiguous_project_binding` | Step 6: no binding on the issuer's policy matches the token, or bindings for two projects do; send `x-tars-project` |
| `400` | `credentials_conflict` | Step 6: the request carries a token and an `x-api-key` header that is not the same token (before 0.12.0, any `x-api-key` header beside a token) |
| `401` | `unregistered_issuer` | Step 3: no policy on this gateway names the token's `iss`, which must match exactly |
| `401` | `wrong_audience` | Step 1: the identity provider issues this client a different audience |
| `401` | `bad_signature`, `unknown_kid` | Step 3: the key set does not hold the key the token was signed with |
| `401` | `expired` | Step 6: request a new token |
| `403` | `project_not_served` | Prerequisites: the gateway does not serve the project the header names |
| `403` | `token_not_accepted` | Step 5: the project accepts API keys only on this gateway |
| `403` | `issuer_not_accepted` | Step 3: the issuer is registered on the gateway for another project, or this project's policy is disabled |
| `403` | `missing_scope` | Steps 1 and 3: the token lacks a required scope, or its `scope` is empty |
| `403` | `environment_claim_missing`, `environment_mismatch` | Steps 1 and 2: the token has no `deployment_env` claim, or its value is not the gateway's environment |
| `403` | `environment_undeclared` | Step 2: the gateway declares no environment |
| `403` | `no_matching_rule`, `rule_for_other_project` | Step 4: no rule matches the token's `client_id`, or the matching `jit` rule names another project |
| `403` | `principal_cap_reached` | Step 4: the rule has created as many applications as `jitPrincipalCap` allows |
| `503` | `keys_unavailable` | Step 3: the gateway has not fetched the key set yet. Retry |

Where to go next

  <Link to="/agent-router-enterprise/guides/operate-and-govern/project-and-data-plane-management/authenticate-gateway-requests/" className="tare-nav-card">
    Authenticate gateway requests with an external IdP
    Every policy field, the project OIDC contract, and what a policy write refuses.
  </Link>
  <Link to="/reference/api/gateway-auth-policies/agentrouter-admin-v-1-gateway-auth-policy-service/" className="tare-nav-card">
    Gateway auth policy API
    The complete request and response fields for policies and identity mapping rules.
  </Link>
