OAuth overview

The Listo REST API is protected by OAuth 2.0 using the client_credentials grant. The Service Bus queue uses a separate credential — a SAS connection string — which is covered on its own page.

This page describes the OAuth flow at a conceptual level. The wire-level contract (request and response shapes, claims, error codes) is on Obtaining tokens.

When OAuth is involved

OAuth tokens are required only on calls to the Sessions API. They are not used to authenticate to Service Bus.

Surface	Credential
GET /v1/tenants/{tenantId}/screenings (Sessions API)	OAuth 2.0 bearer token
Service Bus queue	SAS connection string

The flow

Three things to note:

1. Two parties, not three. client_credentials is a service-to-service grant. There is no end user, no browser redirect, no consent screen. Your service holds the credentials and acts on its own behalf.
2. Tokens are short-lived. Tokens are JWTs valid for around an hour. Cache the token between calls — don't mint a new one per request.
3. The token endpoint is a configuration value. The URL of the OAuth issuer is delivered to you at onboarding alongside your client_id and client_secret. The choice of identity provider is a deploy-time decision and is not part of the public contract.

What's in the token

The bearer token is a signed JWT (RFC 7519). The Listo REST API verifies its signature, audience, and expiry on every request. You generally don't need to decode the token yourself, but if you do, see Obtaining tokens — Claims for the claims we set.

What you must keep secret

• client_secret — bearer-equivalent. Anyone who has it can mint your tokens. Store it in a secrets manager, never in source control.
• The bearer token itself, while it's valid. Once it expires it has no power.

Where to next

• Obtaining tokens — exact request and response shape, JWT claim list, error catalog.
• Authorization header on REST calls.