Delegation & Token Exchange¶

Delegation allows an agent to act on behalf of a user or organization with reduced permissions. This is done through OAuth 2.0 Token Exchange (RFC 8693).

When to Use Delegation¶

Use delegation when:

• An agent needs to perform actions for a user
• The agent should have limited, time-bound access
• You need audit trails showing both the user and agent
• You want the ability to revoke agent access independently

Token Exchange Flow¶

1. User authenticates and receives an access token
2. Agent authenticates and receives its own access token
3. Agent exchanges both tokens for a delegated token
4. Agent uses delegated token to act on user's behalf

Request Format¶

curl -sS "$SIGID_AUTH_ORIGIN/oauth/token" \
  -u "$SIGID_CLIENT_ID:$SIGID_CLIENT_SECRET" \
  -H "content-type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  --data-urlencode "subject_token=$USER_ACCESS_TOKEN" \
  --data-urlencode "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "actor_token=$AGENT_ACCESS_TOKEN" \
  --data-urlencode "actor_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
  --data-urlencode "audience=https://api.example.com" \
  --data-urlencode "scope=limited:scope"

Delegated Token Design¶

Response¶

The delegated token contains:

{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "limited:scope"
}

The access token includes:

• sub: The acting agent's pairwise subject
• subject_type: agent
• act: The grantor chain, including delegation IDs
• aud: The intended audience
• scope: The reduced scope

For SigID-issued delegated tokens, the acting agent stays in sub; the human or agent granting authority appears in act. Do not reverse these when looking up the resource owner. See the exact shape in Claims And Scopes.

Validation¶

Resource servers should:

1. Verify the token signature and expiry
2. Check subject_type = agent and identify the acting agent from sub
3. Validate the grantor and delegation context in act against your resource policy
4. Verify scope is appropriately narrow
5. Enforce issuer, audience, tenant, lifetime, and resource-level access checks

The JavaScript validator rejects delegated tokens unless allowDelegation is set. Enabling it permits the act claim; it does not validate your application's delegation policy or prove fresh human approval. Apply those checks separately.

Revocation¶

Revoke the delegation to withdraw its authority. SigID cascades that revocation to descendant delegations and their bound token-exchange sessions, blocking further exchanges and refreshes through the revoked chain.

An external API that performs only local JWT verification cannot observe a revocation by checking the signature again: an already-issued token may remain cryptographically valid until expiry. Match token lifetimes and any supported live authorization checks to the resource's requirements. Revoking a login session is not a substitute for explicitly revoking delegated authority.

Agent-Initiated Device Ceremony¶

When the agent must obtain human AAL2 approval without a pre-existing user token to exchange, use the device-style flow in Agent Self-Serve Quickstart (POST /api/v1/agents/delegations/device and the hosted /device/delegation/{user_code} page). That path creates the delegation record and returns a delegated token with the human’s act evidence. RFC 8693 exchange on this page remains the path when both a user subject token and an agent actor token are already available.

See Also¶

• Agent Self-Serve Quickstart - Device-flow human approval
• Agent Authentication - Agent auth methods
• Verify Tokens - Validating delegated tokens