How does delegation work?
Agents act on behalf of travelers using short-lived JWTs. Hostrail 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.
This is what lets Hostrail behave as a real booking layer for AI agents rather than just an anonymous inventory API.
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-issuersReturns active issuers with JWKS URL and allowed audiences.
In practice, most runtimes discover auth metadata from the root site first, then use delegation only on traveler-bound write flows such as booking confirmation and cancellation.