Skip to main content

JWT and claim trust

hosting-service checks Bearer JWTs from identity-service and reads a few claims for authorization. It does not store users, and it does not call identity-service again on each API request.

Send the token as Authorization: Bearer your_access_token_here.

What gets verified​

Tokens must include exp. The signature is checked as RS256 against a JSON Web Key Set (JWKS). The token kid header must name a key in that set. An unknown or missing kid is rejected, including when the set contains one key.

In production, hosting-service fetches JWKS from IDENTITY_JWKS_URL, or from {IDENTITY_SERVICE_URL}/.well-known/jwks.json when that URL is not set. Pinning with IDENTITY_JWKS_FILE or IDENTITY_JWKS is optional and wins over a fetch when set.

When DEBUG=false, the process refuses to start unless all of these are set:

  • IDENTITY_ISSUER: the JWT iss claim must match
  • IDENTITY_AUDIENCE: the JWT aud claim must match
  • At least one JWKS source: IDENTITY_JWKS_FILE, IDENTITY_JWKS, IDENTITY_JWKS_URL, or IDENTITY_SERVICE_URL (the service does not fall back to localhost in production)

JWT_HS256_FALLBACK_SECRET verifies HS256 tokens from a local identity-service debug setup. Set it to that service's SECRET_KEY. hosting-service refuses to start with the secret set while DEBUG=false, unless ALLOW_JWT_HS256_FALLBACK=true.

Issuer and audience checks run only when the matching variable is set. Production always sets both.

Claims hosting-service trusts​

These claims are taken from the verified payload. hosting-service does not ask identity-service whether they are still true on the next request:

ClaimUsed for
user_metadata.is_staffStaff operations: global metrics, access updates for any company, stats with no company filter
user_metadata.is_company_ownerCompany metrics, and read access to the waitlist for that company
pat_agmGlobal Prometheus metrics for a personal access token (PAT) issued by staff
company_idWhich company's apps, deployments, and metrics this caller may touch
user_id or subNumeric identity user id stored on apps, deployments, and the event log
emailActor email on events, when the token carries one

A forged payload cannot pass unless it is signed by a key in the configured JWKS. Privileged routes rely on that signature check and on token expiry. hosting-service does not re-fetch the staff flag from identity-service before it acts.

Company scope​

App and deployment routes compare company_id on the token with App.company_id. You only see your company's rows.

Staff tokens can update hosting access for a company_id in the request body, and can read GET /hosting/v1/stats with no company filter. Metrics routes reject a company_id query parameter. GET /hosting/v1/metrics uses the company on the token and requires staff or a company owner. GET /hosting/v1/metrics/all requires staff or pat_agm.

Shellui Actions routes under /api/v1/actions/ let staff pass any company_id query parameter. Company owners may omit it or pass their own. Another company returns 403.