Request context
Understand tenant, location, and staff resolution for Trellis API requests.
Trellis resolves tenant, location, and actor context before an operational route runs. Browser clients authenticate with a Hexclave bearer token; the token, not an identity header, determines the user.
Context headers and credentials
| Value | Purpose | Trust boundary |
|---|---|---|
Authorization: Bearer … | Hexclave access token | Signature, issuer, audience, expiry, and subject are verified by Trellis |
x-tenant-id or x-tenant-slug | Select the tenant in which membership is resolved | Does not authenticate the user |
x-location-id | Scope location-aware reads, writes, roles, and audit entries | Does not grant location access |
vps_… bearer token | Location-scoped POS passcode session | Resolved from a hashed, active database session |
tpk_live_… bearer token | External Trellis Tables API credential | Uses its own tenant, scope, location allowlist, rate limit, and audit boundary |
Identity headers are not authentication
x-auth-provider, x-auth-user-id, and x-staff-user-id are not production authentication mechanisms. They are available only to isolated in-process integration tests.
Staff resolution
- Verify the token. Trellis verifies the Hexclave JWT against the configured JWKS endpoint.
- Resolve membership. The JWT subject is resolved against an active
staff_usersrecord inside the selected tenant. - Build authorization. Tenant-wide and location-specific roles produce the primitive set used by protected routes.
- Fail closed. Protected routes reject requests without an active staff mapping or the required authorization primitive.
curl http://localhost:3000/orders \
-H 'Authorization: Bearer <hexclave-access-token>' \
-H 'x-tenant-slug: trellis-local' \
-H 'x-location-id: loc-tasting-room'Audit entries capture the resolved subject, staff record, tenant, location, request ID, IP address, user agent, and route-specific metadata.