Vendor App Auth & Credentials

This page explains how your marketplace app authenticates to the ROLLER
Platform API and how the scope model decides which endpoints your key may
call. It is vendor-focused; the generic reference pages it links to
(Authentication, Scoped Permissions)
carry the full detail.

🔒

Credential handling. Every credential shown here — the delivered

client_id / client_secret pair and the bearer token — is a live secret. Store them
encrypted at rest, never log them, and never embed them in client-side code.
All values in this guide are illustrative placeholders, not real keys.

1. Where your credentials come from

A live marketplace app does not generate its own key. When an operator
installs your app, ROLLER mints a per-venue client key — a client_id and
client_secret pair, scoped to the permissions your app declared and was approved
for — and delivers it once in the venue.connect webhook body. Your app
stores that pair against the venue and uses it to authenticate every subsequent
request for that venue. These are the exact client_id / client_secret values
you exchange for a bearer token in §2 below.

• The client_secret is delivered exactly once and is never re-sent. Persist both
  values encrypted; if you lose the secret, the operator must reconnect (which
  rotates the credential).
• A credential is scoped to a single venue, per environment — a client key
  minted in Playground will not work in Live, and vice-versa.

For the full connect/disconnect delivery contract, see
Integration Apps. For manual key generation while testing
before your app is live, see Getting API Access.

2. The OAuth2 client-credentials flow

The Platform API uses the OAuth2 client-credentials grant. You exchange a
client_id / client_secret pair for a short-lived bearer token, then send
that token on every API request.

Request a token — POST https://api.roller.app/token with a JSON body:

Content-Type: application/json

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret"
}

📘

ROLLER's /token takes a JSON body with just client_id and

client_secret — there is no grant_type form parameter and the request is
not application/x-www-form-urlencoded. Both fields are required; omitting
either returns 400.

Response:

{
  "access_token": "<bearer-token>",
  "token_type": "Bearer",
  "expires_in": 86400
}

Call the API with the token:

Authorization: Bearer <access_token>
Accept: application/json

• Tokens are short-lived (expires_in, typically 24 hours). Reuse the
  current token until it is near expiry. For production traffic, refresh
  proactively — request a new token when fewer than ~60 seconds of lifetime
  remain — so you avoid a live-traffic 401. As a fallback, always re-request on
  a 401 and retry the call once.
• Do not request a new token per call — repeated token requests can return
  429 (Too Many Requests) and lead to suspension of your credentials.
• The /token endpoint itself requires no scope — any enabled key can request
  a token. Scope is enforced on the resource endpoints, not on token issuance.

See Authentication for expiry, caching, and rate guidance.

3. The scope model

Every key carries a scope: the set of endpoints it is allowed to call. When
your app calls an endpoint outside its scope, the API responds:

HTTP 403 Forbidden
{ "Message": "Invalid scope" }

A key holds one of three access models:

There are 81 grantable scopes in the catalog, each mapping one operation to
one scope identifier (e.g. Booking_Get, ProductAvailability_Get,
Payment_Create). Scope identifiers are case-sensitive. The full catalog,
grouped by resource, is on the Scoped Permissions page,
and every operation in the API Reference
declares its required scope in its OAuth2 security requirement.

🚧

Restricted endpoints. All Staff endpoints are restricted: they are

never covered by full access, must be explicitly granted on the key, and the
venue must additionally be enabled for the Staff Management API.

4. Requesting the right scopes (least privilege)

Because operators see and approve exactly what your key can do, request only
the scopes your integration needs. A typical marketplace checkout integration
declares:

ProductAvailability_Get   Product_Get
BookingDraft_Create       BookingDraft_Costs      BookingDraft_Publish
Booking_Get               Booking_Cancel
Payment_Create
Webhook_Create            Webhook_Get             Webhook_GetFailedMessages

Add Data_* / Reporting_* scopes (or Reporting API full access) only if you
reconcile sales via the Data API. The scope set your app declares becomes part of
what ROLLER reviews before approval and what the operator consents to at install.

5. Key rotation on reconnect

Your granted scopes are fixed to what your app declared and was approved for. If
that approved scope set later changes, the operator is prompted to reconnect;
ROLLER mints a fresh key and sends a new venue.connect for the venue. Treat
a venue.connect for a venue you already hold as a key rotation: replace the
stored key with the new one. See Integration Apps §6.

Next

• API Surface & Support Policy — what
  you may call and the breaking-change commitments.
• Sandbox & Non-Prod Testing — exercise auth against
  Playground before going live.