Set Up Sample Application

Complete the setup once. Every walkthrough below builds on the same starting point.

Before you begin, make sure you have:

ThunderID running locally, with http://localhost:5173 allowed to call it from the browser. After startup, send PUT /server-config/cors with the origin. If you run with declarative resources enabled, you can instead ship the same value as config/resources/server_configs/cors.yaml in the distribution. See Get ThunderID.

The call needs an access token with the system scope. Obtain one for an administrator, export it, then send the origin:
bash
```
export TOKEN="<access-token>"

curl -kL -X PUT https://localhost:8090/server-config/cors \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -d '{ "allowedOrigins": ["http://localhost:5173"] }'
```
The declarative equivalent, for instances that run with declarative resources enabled, is config/resources/server_configs/cors.yaml:
yaml
```
resource_type: server_config
name: cors
value:
  allowedOrigins:
    - "http://localhost:5173"
```
The Wayfinder sample distribution. The Get ThunderID step above already pulls the archive that ships it. It contains a thunderid-config/redirect/ bundle with an importable YAML config and a thunderid.env file, plus the Wayfinder web frontend and the Concierge services.
Node.js 20+ for running the sample's services.
An LLM API key. One of an Anthropic API key from console.anthropic.com or a Google Gemini API key from aistudio.google.com.

Import the Wayfinder configuration bundle.

Edit thunderid-config/redirect/thunderid.env if you want to change the agent's client secret. The default value (wayfinder-agent-secret) matches the sample's defaults.
Import the bundle into ThunderID.
- Sign in to the ThunderID Console at https://localhost:8090/console.
- On first sign-in, a welcome screen appears with an Open button. (Later, reach the same screen from the user profile menu in the top-right corner of the Console.)
- Click Open and select your thunderid-config/redirect/thunderid-config.yaml file from the sample distribution.
- Select your thunderid-config/redirect/thunderid.env file to provide the environment variables referenced in the YAML.
- The Console imports the files and reports the resources it created when the import completes.
The bundle creates everything the sample needs. What these walkthroughs use:
- Resource servers: wayfinder-agent (identifier http://localhost:8790/chat, with agent:access) and wayfinder (identifier http://localhost:8787/mcp, with booking:read, booking:create, booking:cancel, booking:recommend).
- Default resource server: set to wayfinder, so web sign-in tokens that omit resource are bound to the booking API. The chat widget sends resource=http://localhost:8790/chat, and the agent sends resource=http://localhost:8787/mcp for MCP calls.
- Roles: Chat User, Booking User, and Recommender, with users and the agent pre-assigned:
  - Chat User → john.doe.
  - Booking User → john.doe and jane.smith.
  - Recommender → WAYFINDER-CONCIERGE.
- Application: WAYFINDER (public, PKCE, redirects to http://localhost:5173 and /chat-token-callback).
- Agent: WAYFINDER-CONCIERGE (confidential client with the client_credentials and authorization_code grants).
- Flow: Wayfinder Agent Authentication Flow (assigned to the agent).
- Users: john.doe / john.doe and jane.smith / jane.smith (typed as Customer).
Start the sample following the commands in its README.

Walkthrough Structure

Each walkthrough below starts from the setup above. The walkthroughs map onto the patterns from Understand It, so you can read about a pattern and then run it.

Select a walkthrough to begin:

Walkthrough Structure​

Walkthrough Structure