How does delegation work?

Agents act on behalf of travelers using short-lived JWTs. The platform records both "which agent acted" and "on whose behalf."

What is delegation?

When an agent books or cancels a stay, the platform needs to know who the traveler is. The agent attaches a short-lived JWT in the X-Delegated-User header, signed by a trusted delegation issuer.

Which routes require delegation?

Route	Delegation required
`POST /v1/bookings`	Yes
`POST /v1/bookings/{id}/cancel`	Yes
All other routes	No

JWT requirements

Claim	Required	Description
`iss`	Yes	Must match a registered delegation issuer
`sub`	Yes	Traveler identifier
`aud`	Yes	Must include the platform's audience
`exp`	Yes	Keep short (minutes, not hours)

Accepted algorithms: RS256, ES256.

Error codes

Code	Status	Recovery
`delegation_required`	401	Mint a JWT and retry
`delegation_invalid`	401	Check `detail.reason`, remint
`delegation_issuer_unknown`	401	Escalate to tenant admin

detail.reason values for delegation_invalid: expired, bad_signature, missing_claim, audience_mismatch, unsupported_algorithm.

Discovering trusted issuers

GET /.well-known/delegation-issuers

Returns active issuers with JWKS URL and allowed audiences.