Caller context binding

When multiple callers share an AI agent surface, the gateway must identify which caller is making each request at the moment of every outbound call. Without this, it cannot determine whose delegated credentials to inject, and one caller’s access token could be silently reused for another caller’s request.

The gateway solves this through a three-part composite key that uniquely scopes every delegation context. The key combines the agent’s stable cryptographic identifier, a privacy-preserving hash of the caller’s identity, and the external provider identifier. No two callers on the same surface produce the same key, and the vault entry created during consent can only be resolved by the same combination that created it. Configure per-caller Credential Delegation →

How vault entries are scoped

Each delegation vault entry is scoped to three values:

A vault entry created during one caller’s consent can only be resolved by the same caller, on the same surface, for the same provider. Tokens are encrypted at rest using the gateway’s own key material.

The agent DID component identifies the workload, which is normally the managed agent itself, but it is resolved independently of the user identity hash and can vary by configuration: an Identity element set to extract a caller’s JWT claim produces a per-caller DID here too, while a Static DID or payload-based extraction keeps this component constant across every caller on the surface. Either way, the user identity hash is what guarantees the entry is scoped to one caller, because it is always derived from the caller’s own source-authentication credential rather than from whatever the Identity element is configured to extract.

How caller identity is stored privately

The user identity hash is a SHA-256 digest (hash) of the single raw credential that source authentication established for the caller: the JWT sub claim for JWT Bearer, the key name for API Key, the DID for DID Auth, or the certificate principal for mTLS. This computation reads directly from the Caller Context element’s authentication result, not from an Identity element’s derived DID, and not from any of the other claims a JWT might carry. Raw credential values are never stored; only the derived hash is held in the vault.

Relationship to Credential Delegation

Caller context binding and Credential Delegation are separate concerns that are easy to conflate because they always operate together: Credential Delegation cannot store or inject a token without a caller identity to scope it to.

Caller context binding is limited to producing the composite key described above, from an already-authenticated caller. It has no concept of consent, token injection, refresh, or revocation. Those behaviours belong entirely to Credentials, which documents the consent and elicitation modes, how a token is injected once resolved, how expired tokens are refreshed, and how an administrator revokes a stored token. This page only explains how the caller side of that lookup key is identified and kept private.

Relationship to Workload Binding

Caller context binding and Workload Binding are two distinct features that both involve the caller’s identity.

Workload Binding embeds the caller’s context into a signed VP on an outbound edge. It can be placed on a Transit Point (where a Gateway Connection target carries the VP to a receiving gateway for verification) or on the target leg (where the VP is attached to any outbound request). The receiving gateway verifies the VP and exposes the caller context to OPA as input.identity_binding. See Workload Binding for a full explanation.

The two mechanisms draw from different data sources and do not depend on each other. The vault stores an encrypted OAuth token and uses the identity hash only as a lookup key. Raw credential values are never persisted. Workload Binding never reads the vault. Instead, it reads live claims from the authenticated request: from the transit token, which carries claims captured at the Access Point, or from the Bearer JWT the managed agent presents at the Transit Point. The same caller’s request feeds both independently.

Use cases

Multi-user agent deployments. A single agent surface serves many callers, each mapped to their own composite key. One caller’s vault entry can never be resolved by another caller’s request, so a surface can safely serve callers who each hold access to the same downstream provider under different accounts. How a vault entry is first created and kept current is a Credential Delegation concern; see Credentials.

Per-caller attribution. The identity hash ties every vault entry, and every audit event derived from it, to one specific caller without exposing their raw identity claims. Combined with the audit log, every outbound API call can be traced back to the caller who authorised it.

Isolated revocation. Because each caller’s vault entries are keyed independently, an administrator can revoke one caller’s access to a provider, or every provider they hold tokens for, without affecting any other caller on the same surface. See Managing delegated tokens for how to revoke a token.