# Carry caller claims through your managed agent > Choose which of a caller's token claims the gateway passes to your managed agent in the transit token, and on through a Transit Point to the policies of a connected gateway. This guide sets which of the caller’s token claims your gateway carries past your managed agent. The gateway adds them to the transit token on each request it forwards to the managed agent, and a Transit Point’s Workload Binding element copies them into the signed Verifiable Presentation (VP) that the connected gateway reads. For background, see [Caller context binding](/products/affinidi-trust-fabric/agent-gateway/concepts/caller-context-binding.md) and [Workload binding](/products/affinidi-trust-fabric/agent-gateway/concepts/workload-binding.md). Without an allowlist, the caller’s claims stay at your gateway’s Access Point. Calls your managed agent makes through a Transit Point then reach the connected gateway with no record of the caller, so its policies cannot decide based on who the caller is. Use this guide when: - Your managed agent calls a connected gateway through a Transit Point on a caller’s behalf. - The connected gateway, or your managed agent itself, needs specific caller claims such as an organisation or role. - You want to pass on only the claims that are needed, rather than the caller’s whole token. When the Managed Agent’s own target is the connected gateway, bind the claims on that target leg instead, as in [Bind caller identity to your agent’s outbound calls](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/connections/bind-caller-identity-to-outbound-agent-calls.md). ## Prerequisites | Requirement | Details | | Dashboard access | Permission to edit surfaces. | | Callers who sign in with JWT Bearer | A Caller Context element set to JWT Bearer, with a policy that refuses callers whose token failed validation. See [Validate bearer tokens on a surface](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/access/validate-bearer-tokens-on-a-surface.md). Claims are carried only for callers who sign in this way. | | Transit Point to the connected gateway | A Transit Point with Endpoint Type set to via Gateway Connection, and an Identity element on its Managed Agent → Transit Point edge. See [Bind caller identity to your agent’s outbound calls](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/connections/bind-caller-identity-to-outbound-agent-calls.md), Steps 1 and 2. | | Managed agent that returns the transit token | Your managed agent reads the X-Transit-Token header from each request the gateway forwards to it, and sends it back unchanged on its Transit Point calls. Require transit token stays on for the Transit Point, which is the default. See [Apply policy to outbound calls](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/policies/apply-policy-to-outbound-calls.md). | ## Steps Choose the claims to carry List the top-level claims from your callers’ tokens that something downstream needs, such as sub, email, or an organisation claim. Each claim you list is available in these places: | Where | How it reads them | | Your managed agent | In the transit token on each request the gateway forwards to it, under caller_context_fields. | | Policies on the connected gateway | As input.identity_binding.caller.fields, once the Transit Point’s Workload Binding copies them into the VP. | | Policies on your gateway | A Policy on the request side of the Access Point → Managed Agent edge reads the whole validated token as input.source_auth.claims. A Policy on a Transit Point reads the managed agent’s own request. | The transit token also carries a one-way hash that identifies the caller by how it was identified: the authentication method, the issuer and the principal. Delegated credentials on a Transit Point use it to find the caller’s stored token, and the VP carries it as user_hash. See [Configure per-caller Credential Delegation](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/setup/configure-per-caller-credential-delegation.md). Add Workload Binding to the Transit Point edge - Open the surface on the canvas. - From the Enhancements section of the palette, drag Workload Binding onto the Managed Agent → Transit Point edge. - Select the Workload Binding node and check that Enable workload binding for this Transit Point is on. - Set Caller context source to Transit token. Add the claims to the allowlist Under Caller field allowlist, add each claim from Step 1. Type the name and press Enter or select Add, or select a suggestion such as + sub or + email. The gateway copies each listed claim’s value exactly as it appears in the caller’s token, and leaves out a claim the token does not carry. When the surface has more than one Transit Point using Transit token, the transit token carries every claim on any of their allowlists. Each Transit Point binds only the claims on its own list. Save the surface Close the panel and select the save icon (tooltip: Save changes) on the canvas. Read the claims in your managed agent (optional) The transit token is a signed JWT whose payload your managed agent can read. For example, in Python: ```python import base64 import json def transit_token_claims(token: str) -> dict: payload = token.split(".")[1] payload += "=" * (-len(payload) % 4) return json.loads(base64.urlsafe_b64decode(payload)) claims = transit_token_claims(request.headers["X-Transit-Token"]) caller = claims.get("caller_context_fields", {}) ``` Use these values to tailor what the agent does, and keep access decisions in gateway policies. Only the gateway can check the token’s signature, and it refuses a changed token on the Transit Point call, so send the header back exactly as received. ## Confirm Use a caller token from your identity provider, , that carries every claim on your allowlist. Replace with your surface’s Entry point URL. The tests read the transit token in your managed agent, so have it log the output of transit_token_claims from Step 5. ### Test 1: request with a caller token returns the allowlisted claims to your managed agent curl -X POST "" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}' curl -X POST "" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "A2A-Version: 0.3" \ -d '{"jsonrpc":"2.0","method":"message/send","id":1,"params":{"message":{"messageId":"test-1","role":"user","parts":[{"kind":"text","text":"Hello"}]}}}' Expected: the payload your managed agent logs includes caller_context_fields with the allowlisted claims (across all Transit Points using Transit token) and no others, among the token’s other claims. For an allowlist of sub and org: ```json { "caller_context_fields": { "sub": "alice@example.com", "org": "acme-finance" }, "allowed_transit_points": ["partner"] } ``` ### Test 2: Transit Point call returns identity binding verified on the connected gateway Send a request that makes your managed agent call the Transit Point while it handles it. Expected: on the connected gateway, the Audit page shows an entry titled identity binding verified for the receiving surface. A policy there that checks input.identity_binding.caller.fields, such as the one in [Bind caller identity to your agent’s outbound calls](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/connections/bind-caller-identity-to-outbound-agent-calls.md), records a policy decision titled Allowed. The connected gateway keeps these records when its VP Audit settings include Identity Binding Verified and Policy Decision. ### Test 3: caller token missing an allowlisted claim returns only the other claims Repeat Test 1 with a token that lacks one allowlisted claim, such as org. Expected: caller_context_fields holds the other claims and has no org entry. ## Troubleshooting | Symptom | Likely cause | Fix | | The transit token has no caller_context_fields. | No Workload Binding on a Transit Point of this surface uses Transit token, or the caller’s token failed validation, or the caller signed in with a method other than JWT Bearer. | Check Steps 2 and 3, and that the caller’s token passes your JWT Bearer strategy. | | The forwarded request has no X-Transit-Token header. | The surface has no Transit Point. | Add a Transit Point to the surface. The gateway issues a transit token only for surfaces that have one. | | The Transit Point call returns 401 with Transit token missing or invalid. | The managed agent did not send the token back, changed it, or sent it after the token expired (5 minutes by default, plus a few seconds of clock allowance). | Send the header back exactly as received, during the same request. | | The connected gateway sees fewer claims than your managed agent does. | Each Transit Point binds only the claims on its own allowlist. | Add the claim to that Transit Point’s Caller field allowlist. | | The allowlist shows an error that a caller field uses nested path syntax. | The name contains a dot, such as org.id. | Use a top-level claim name. | ## Next steps - [Bind caller identity to your agent’s outbound calls](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/connections/bind-caller-identity-to-outbound-agent-calls.md): check the claims in a policy on the connected gateway. - [Configure per-caller Credential Delegation](/products/affinidi-trust-fabric/agent-gateway/how-to-guides/setup/configure-per-caller-credential-delegation.md): act on each caller’s own account at a third-party API. ## Related - [Outbound binding elements](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/outbound-binding.md#workload-binding): every Workload Binding field. - [Surface routing model: the transit token](/products/affinidi-trust-fabric/agent-gateway/concepts/surface-routing-model.md#the-transit-token): how the transit token links inbound and outbound calls. - [Transit Points](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/transit-points.md): outbound routes and the transit token requirement. - [OPA policies](/products/affinidi-trust-fabric/agent-gateway/reference/surfaces/opa-policies.md): the policy input schema.