ID token claims

AgentKeychain issues standard OIDC ID tokens with a few additions that describe the agent and its human owner. Everything is either a standard OIDC claim or a namespaced custom claim — no reserved names are overloaded.

Required claims

These are always present on every ID token AgentKeychain issues.

Claim	Description
`iss`	Issuer. Always `https://agentkeychain.com`.
`sub`	Pairwise pseudonymous identifier for the owner — the human who delegated authority. Unique per owner-client pair.
`aud`	Your `client_id`.
`iat`, `exp`, `auth_time`	Standard OIDC timestamps.
`nonce`	Echo of the nonce you sent in the authorization request. Verify it matches.
`act`	Actor claim per RFC 8693. Identifies the agent as the acting party on behalf of the owner. Contains `sub` — the agent’s pairwise identifier.
`https://agentkeychain.com/agent_id`	The agent’s global identifier, stable across clients. Namespaced to avoid collision with standard OIDC claims.

Optional claims

Included when the owner’s permission settings allow.

Claim	Description
`https://agentkeychain.com/agent_name`	Human-readable agent name (e.g. “CalendarBot”).
`https://agentkeychain.com/platform`	Agent platform — `claude`, `openai`, `custom`, etc.
`https://agentkeychain.com/owner_id`	The real AgentKeychain user identity of the owner. Only included when the owner has explicitly enabled “Share identity” for your client.

Example payload

{
  "iss": "https://agentkeychain.com",
  "sub": "pw_owner_r8t2m4",
  "aud": "akc_client_wiki123",
  "iat": 1775383200,
  "exp": 1775386800,
  "auth_time": 1775383195,
  "nonce": "n-xyz...",
  "act": {
    "sub": "pw_agent_x7k9m2"
  },
  "https://agentkeychain.com/agent_id":   "agent_abc123",
  "https://agentkeychain.com/agent_name": "CalendarBot",
  "https://agentkeychain.com/platform":   "claude"
}

Read this as: owner pw_owner_r8t2m4 delegated authority to agent pw_agent_x7k9m2 (globally agent_abc123) to act on client akc_client_wiki123.

Pairwise subjects

Both sub (owner) and act.sub (agent) are pairwise pseudonymous identifiers — deterministic per owner-client pair, but not correlatable across clients. Two clients cannot tell that they’re talking to the same person or the same agent.

Same sub on the same client across sessions → same owner.
Same act.sub on the same client across sessions → same agent.
Same sub but different act.sub → two different agents owned by the same person.

Why the act claim matters

The act claim is the canonical signal that this is an agent session, not a direct human session. No other OIDC provider issues it — its presence alone is enough to branch on.

if (token.act) {
  // agent session — apply agent-specific policies
}

Linking to existing accounts

Because pairwise sub values are issuer-specific, an AKC sub and a Google sub for the same human are different strings. You can’t join them directly.

Two options:

Prompt to link. On an agent’s first sign-in, ask the owner to log in with their human SSO and link the two sessions. Store the mapping on your side.
Opt-in identity sharing. Request the agent_identity scope. When the owner has enabled identity sharing for your client, the token includes https://agentkeychain.com/owner_id — a stable cross-provider correlation key.

Next: Scopes →