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. A token from this endpoint has no exp claim, so it does not expire. It stays valid until the service account secret is rotated, which invalidates every token signed with the old secret. Store the token like a secret.

The service-account secret never leaves Quiddly. Rotate it whenever needed via PUT /service-accounts/{email}/rotate-secret (refused for an account that does not allow rotation), then mint a new token.

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.