Avnology ID
Guides

AI Agents (On-behalf-of)

Let an AI agent act on behalf of a human user with RFC 8693 Token Exchange and a first-class agent identity.

AI Agents (On-behalf-of)

An agent identity in Avnology ID is a first-class machine identity that is owned by a human user. It lets an AI agent, assistant, or autonomous workflow act on behalf of that user with:

  • Time-limited scope — exchanged tokens are short-lived and audience-scoped.
  • Attribution — the exchanged token carries both the user (sub) and the agent (act.sub), so every downstream API call is auditable to both parties.
  • Revocability — revoking the agent identity or the user's session revokes every token the agent has ever minted.

This page shows the end-to-end flow: create an agent, exchange a user token for an on-behalf-of token, then verify it on the resource server.

When to use this vs. other patterns

Use casePatternWhy
AI assistant calling APIs on behalf of a signed-in userAgent identity + Token Exchange (this page)User stays the sub; agent recorded as act; short-lived.
Background daemon, cron, CI/CDPlain service account + client credentialsNo human in the loop.
Support engineer acting as a customerAdmin impersonation (guide)Admin policy, MFA gate, email notification.
Generic cross-service delegationRaw RFC 8693 Token Exchange (guide)Service-to-service, no human sub.

What an agent identity is

An agent identity is a service account with owner_id set to the delegating user. It shares the machine-identity model with plain service accounts (API keys, scopes, revocation) but adds the human-owner backlink so token-exchange flows can bind exchanged tokens to act.sub = agent and sub = user.

User (human)                    ──owns──▶  Agent (service account)
  ├── owns agents                             ├── owner_id = user:jane
  ├── issues user access tokens               ├── api_keys[]
  └── delegates scope                         └── scopes[] (subset of user's)

The shape already exists — owner_id is part of ServiceAccount in the public API. No new resource type; the docs + SDK helper just make the "agent" intent first-class.

End-to-end flow

                                            ┌──────────────────────────┐
                                            │  Avnology ID             │
                                            │  (api-id.avnology.net)   │
                                            └──────────────────────────┘
                                                   ▲         ▲
     1. User signs in, gets access token           │         │
        ──────────────────────────────────────▶    │         │
                                                   │         │
     2. Admin creates agent (service account,      │         │
        owner_id = user, scopes = subset)          │         │
        ──────────────────────────────────────▶    │         │
                                                   │         │
     3. Admin issues API key for the agent     ◀───┘         │
                                                             │
     4. Agent holds: user's access token + its own API key   │
                                                             │
     5. Agent exchanges: subject=user_token,                 │
        actor=agent ────────────────────────────────────▶    │
                                                             │
     6. Avnology ID issues an access token with          ◀───┘
        sub=user, act.sub=agent, scope=intersection
                                                   │
     7. Agent calls downstream API with the exchanged token

Prerequisites

RequirementDescription
User access tokenObtained from a regular login or OAuth code exchange.
Agent identityA service account created by an admin with owner_id pointing at the delegating user.
Agent credentialEither the agent's API key (server-side) or a signed assertion (advanced).
token_exchange scopeThe OAuth client used by the agent must include token_exchange.
AudienceThe exchanged token's aud claim determines which resource server accepts it.

1. Create the agent identity (admin)

An admin creates the agent for the delegating user. This is the standard service-account create flow; the only special field is owner_id.

import { AvnologyId } from "@avnology/sdk-typescript";

const admin = new AvnologyId({
  baseUrl: "https://api-id.avnology.net",
  apiKey: process.env.AVNOLOGY_ADMIN_KEY!,
});

const agent = await

2. Agent exchanges user token for an on-behalf-of token

The auth.exchangeForAgent helper wraps RFC 8693 with sensible defaults for the agent-on-behalf-of-user pattern. It sets the grant type, the subject-token type, and the actor-token type so you only supply the identifiers.

The response is a standard TokenSet — accessToken, tokenType: "Bearer", expiresIn, optional refreshToken.

3. Verify on the resource server

On your downstream API, verify the JWT locally using @avnology/backend. The act claim lets you branch on "is this an agent call?" and log both identities for audit.

import { JWTVerifier } from "@avnology/backend";

const verifier = new JWTVerifier({
  issuer: "https://api-id.avnology.net",
  audience: "https://api.acme.example",
});

export async function handler

Security notes

References

Admin Impersonation

Securely impersonate users for debugging and support using token exchange with full audit trails.

Custom Domains

Use your own domain (e.g., login.yourcompany.com) for branded sign-in experiences.

On this page

AI Agents (On-behalf-of)What an agent identity isEnd-to-end flowPrerequisites1. Create the agent identity (admin)2. Agent exchanges user token for an on-behalf-of token3. Verify on the resource serverSecurity notesReferences