See It in a Sample App
Each walkthrough on this page runs one of the agent identity patterns from Understand It against a working sample.
Meet Wayfinder
Wayfinder is a travel-booking application with an AI agent built in, the Wayfinder Concierge, an in-app chat assistant. Through Wayfinder, consumers search for flights and hotels, book trips, and ask the Concierge to do the same on their behalf.
These walkthroughs involve two principals: consumers who book travel and chat with the agent, and the Wayfinder Concierge that acts as their assistant. Each carries its own identity in ThunderID. The bundle registers more than these; what follows is what the walkthroughs touch.
Meet the Cast
- Consumers book travel and chat with the agent.
- John Doe is the customer with full access. He can book through the UI and talk to the Wayfinder Concierge. He carries both the
Booking UserandChat Userroles. - Jane Smith also books through the UI, but does not have access to the Wayfinder Concierge. She carries only the
Booking Userrole.
- John Doe is the customer with full access. He can book through the UI and talk to the Wayfinder Concierge. He carries both the
- The Wayfinder Concierge is a first-class principal in ThunderID with its own credentials. It uses its own identity for browsing tools, and switches to a user-context token when a tool needs the consumer's consent.
Sample Architecture
Wayfinder runs as three deployable pieces. The Wayfinder Web browser app hosts the chat widget, the AI Agent drives the conversation, and the Wayfinder Server exposes booking data over MCP.
ThunderID sits alongside as the identity authority. It issues a user token on sign-in, an agent token for the agent itself, and an on-behalf-of (OBO) token when the agent acts for the consumer. The Wayfinder Server also fetches ThunderID's JWKS to validate every incoming JWT.
Identity Model
The setup below creates a set of ThunderID resources. Here is what each one is and how it maps to Wayfinder concepts.
Organization Unit
ThunderID can host many isolated organization units side by side. Wayfinder needs only one, so everything lives in the default unit.
User Types
A user type defines who can exist in the system and what attributes they carry. Each user record belongs to exactly one user type. The walkthroughs use the Customer user type, which the two demo consumers John Doe and Jane Smith belong to, with standard attributes like username, email, and name.
See User Types.
Resources and Permissions
The AI Agent API and the Wayfinder Server both need protection in the sample. The AI Agent API decides who is allowed to chat with the agent at all, and the Wayfinder Server decides who can book travel. Each is registered as a resource server, with its actions generating one permission per action.
A resource server groups the APIs of one backend. Each resource server defines one or more resources, each resource defines actions, and ThunderID generates a permission of the form <resource>:<action> for every action. Nested resources extend the chain.
wayfinder-agent (Resource Server)
└── agent (Resource)
└── access → agent:access (Permission)
wayfinder (Resource Server)
└── booking (Resource)
├── read → booking:read (Permission)
├── create → booking:create
├── cancel → booking:cancel
└── recommend → booking:recommend
Permissions travel in the access token as its scope. See Resource Servers.
Roles
A role bundles permissions for a class of principal. A user's or agent's effective permissions are the union of permissions across their roles. The walkthroughs use three of the roles the bundle creates:
Chat User: grantsagent:access, the permission required to talk to the Wayfinder Concierge.Booking User: grantsbooking:read,booking:create, andbooking:cancelfor booking travel through the UI.Recommender: grantsbooking:recommend, the permission the Wayfinder Concierge needs to surface flight recommendations on its own.
John Doe carries both user roles; Jane Smith carries only Booking User. The Recommender role is assigned to the WAYFINDER-CONCIERGE agent, not to a user.
See Authorization.
Application
An application is the OAuth2 client that ThunderID issues tokens to. Wayfinder Web is registered as WAYFINDER, a public browser client that uses PKCE (Proof Key for Code Exchange), which stops a stolen authorization code being redeemed by anyone else.
See Manage Applications.
Agent
An agent is a first-class non-human principal in ThunderID with its own credentials. The Wayfinder Concierge is registered as WAYFINDER-CONCIERGE, with two grants enabled:
client_credentials: for the agent's own token, used to call browsing tools.authorization_code: for the on-behalf-of flow, where the user consents and the agent calls mutating tools as the user.
See Create and Manage Your Agent and Act on Behalf of a User.
Flows
A flow is the sequence of steps a user moves through when signing in or granting consent. Wayfinder Web uses its own Wayfinder App Authentication Flow for sign-in, with separate registration and password-recovery flows attached. The agent uses a separate Wayfinder Agent Authentication Flow that drives the OBO consent screen.
See Build a Flow.
Set Up the Sample
Before running any walkthrough, set up the Wayfinder sample application. Two paths lead to the same end state:
Walkthroughs
Once the sample is running, pick a walkthrough:
