Authentication

Every Quiddly API request is authenticated via a bearer JWT in the Authorization header:

Authorization: Bearer <jwt>

Integrators obtain a JWT from a Quiddly service account (Flow 1). Some partner integrations instead use Auth0-issued machine tokens that Quiddly provisions (Flow 2) - you do not call Auth0 yourself.

Flow 1 - Service account (HS256)

The standard flow for server-to-server integrations.

1. Quiddly provisions a service account for your tenant. Contact support; see Getting started. Self-service creation is on the roadmap.
2. Mint a JWT with PUT /service-accounts/{email}/generate-token (requires GenerateTokenServiceAccount). The token is signed HS256 by Quiddly; use it directly.
3. Tokens expire after 23 hours. Re-issue on demand; do not refresh in parallel from many workers.

The service-account secret never leaves Quiddly. Rotate it whenever needed via PUT /service-accounts/{email}/rotate-secret.

Note

A service account’s reach depends on its role. A SYSTEM role account can act across the whole tenant and every client with one token; a client-scoped account is limited to that client’s data.

Flow 2 - Machine tokens (RS256)

Some partner integrations authenticate with Auth0-issued machine-to-machine tokens that Quiddly arranges for you. You do not call Auth0 directly - Quiddly provisions the credentials and audience and sets this up with you. These tokens are RS256; their rights come from the permissions claim (Auth0 RBAC), and the scope claim is informational only and not used for authorization.

Errors

HTTP	Cause
401 AUTHORIZATION_HEADER_MISSING	No Authorization header sent.
401 INVALID_HEADER	Header malformed, wrong algorithm, or bad signature.
401 TOKEN_EXPIRED	JWT past its exp claim. Re-issue.
403 ACCESS_DENIED	Token valid, but principal lacks the required right.

CORS

The API allows cross-origin requests from the developer portal of the same tenant. The interactive reference uses fetch with credentials omitted; if you build a browser-side integration, supply the JWT manually in the Authorization header.