Scopes

AgentKeychain supports three scopes. Request them the same way you would with any OIDC provider — space-separated in the scope query parameter.

Supported scopes

Scope	Returns
`openid`	Required. Triggers the issuance of an ID token. All required claims are returned regardless of other scopes.
`profile`	Adds the optional agent metadata claims — `agent_name` and `platform` — subject to the owner’s permission settings.
`agent_identity`	Opts into the `owner_id` claim for account linking. Only returned when the owner has enabled “Share identity” for your client in the dashboard.

Requesting scopes

scope=openid+profile+agent_identity

Grant is not guaranteed. The token response echoes the scopes actually granted — always read from the response, not from the request:

{
  "access_token": "at_...",
  "id_token":     "<signed JWT>",
  "scope":        "openid profile",
  // agent_identity was requested but not granted
  ...
}

When scopes get narrowed

The owner hasn’t enabled identity sharing for your client → agent_identity is dropped.
The owner hid the agent’s display name for your client → agent_name is omitted even with profile.
Your client isn’t allowlisted for a particular scope → the request fails with invalid_scope.

Minimize by default. Request only openid profile unless you actually need account linking. Owners are more likely to approve your client for low-surface-area scopes, and users expect agents to run with minimum permission.

← Back to Introduction