Acting on Behalf of a User

Booking a flight commits a real action against the user's record. The agent's own permissions are not enough. The action has to happen as the user, with the user's consent, and only for the scopes the user actually grants.

In this walkthrough, John asks the agent to book a flight. The chat pauses, a popup opens where John picks which booking permissions to grant, and the booking goes through under a delegated token.

Prerequisites

Complete Setup before starting this walkthrough.

Background

Connect to Services → The agent acts on behalf of a user covers the requirements story behind this use case.

Walk Through the Use Case

1. Sign in to Wayfinder as john.doe and ask the agent for some flights to choose from:

   What flights are there from Colombo to Singapore?

   Pick any flight number from the results.

2. Send:

   Book flight 2

3. The agent decides this is a mutating tool and returns need_user_consent. A popup opens, hosted by ThunderID. Sign in inside the popup as john.doe.

4. On the consent screen, pick which permissions to grant. Tick at least booking:create for the booking to succeed. You can also grant booking:read and booking:cancel if you want the agent to manage existing bookings in the same session.

5. Approve. The popup closes. The agent picks up where it paused, calls create_booking with the OBO token, and confirms the booking in the chat.

Try a Variant

• Repeat the walkthrough but uncheck booking:create on the consent screen. The agent retries, the tool returns 403, and the agent surfaces the failure honestly in the chat.
• Ask the agent to cancel a booking without granting booking:cancel. Same outcome — the OBO token doesn't carry the scope, the API rejects, and the agent reports back.

Concepts

Consent. This walkthrough is consent in action. John doesn't grant the agent a blanket "do anything bookings-related" — the consent screen surfaces the individual booking:* permissions and the issued token carries only what he ticked. The agent cannot widen its access after the fact.

Delegation. The OBO token identifies both John (as the subject) and the agent (as the actor). Downstream services know the booking was triggered by an agent acting for John, not by John directly. The token's effective permissions are the intersection of what John holds and what John just consented to. See Agent Authentication for the full OBO exchange.

Branding. The consent popup is rendered by ThunderID hosted pages. The Wayfinder sample uses ThunderID's default branding out of the box. To make the popup feel like part of Wayfinder, customize the logo and color theme for the WAYFINDER-CONCIERGE agent from its Design settings in the Console. The same pattern applies to applications — see Register an Application.