Authentication

Getting access and generating credentials

See getting API access.

Requesting an access token

To obtain an access token for the client credentials flow:

• URL: https://api.roller.app/token (See environments)
• HTTP Method: POST
• Content-Type: application/json
• Body - {"client_id":"xxxxxxxxxxxxxx","client_secret":"xxxxxxxxxxxxxxx"}

Which should return a bearer token as per the example below:

{
    "access_token": "cd5c24313225bb9ea046a2ef0f0dbb9f...",
    "token_type": "Bearer",
    "expires_in": 86400
}

Making a request with the token

Once you have a token, a request must include the following:

• Auth Type: OAuth 2.0
• Accept: application/json
• Authorization (Header): Bearer cd5c24313225bb9ea046a2ef0f0dbb9f...

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#0052FF', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0A1128', 'lineColor': '#0052FF', 'secondaryColor': '#E8F0FE', 'tertiaryColor': '#E8F0FE', 'mainBkg': '#0052FF', 'clusterBkg': '#E8F0FE', 'edgeLabelBackground': '#0A1128', 'fontFamily': 'Montserrat, sans-serif', 'fontSize': '14px', 'actorBkg': '#0A1128', 'actorBorder': '#0052FF', 'actorTextColor': '#ffffff', 'actorLineColor': '#0A1128', 'signalColor': '#0052FF', 'signalTextColor': '#0052FF', 'labelBoxBkgColor': '#E8F0FE', 'labelTextColor': '#0A1128', 'loopTextColor': '#0052FF', 'noteBkgColor': '#E8F0FE', 'noteTextColor': '#0A1128', 'noteBorderColor': '#0052FF', 'activationBorderColor': '#FF3B30', 'activationBkgColor': '#E8F0FE'}, 'themeCSS': '.node rect, .cluster rect, rect.actor { rx: 10px; ry: 10px; } .labelBox, .note { rx: 8px; ry: 8px; } .edgeLabel rect, .activation0, .activation1, .activation2 { rx: 4px; ry: 4px; } .nodeLabel, .edgeLabel, .label, .cluster-label, text, tspan, span, p { font-family: Montserrat, sans-serif; }'}}%%
sequenceDiagram
    participant YourApp as Your App
    participant Roller as ROLLER API

    YourApp->>Roller: POST /token<br/>(client_id, client_secret)
    activate Roller
    Roller->>Roller: Validate credentials
    Roller->>YourApp: 200 OK<br/>(access_token, expires_in: 86400)
    deactivate Roller

    activate YourApp
    YourApp->>YourApp: Store token in database/cache
    Note over YourApp: Reuse token for all requests<br/>until 401 response
    deactivate YourApp

    loop On each API call (within token lifetime)
        YourApp->>Roller: GET/POST endpoint<br/>Authorization: Bearer {token}
        Roller->>YourApp: 200 Response
    end

    Note over YourApp,Roller: When token expires or 401 received:<br/>Request new token using same flow

To avoid 429 (Too Many Requests) we recommend calling the token endpoint once and storing the token in a central place such as a database. For performance reasons you may wish to cache the token in your servers too, which means if you have multiple servers you must avoid each one making its own token request.

Expiry

The access token is short-lived - its expiry is provided in the token response and may change, however it will generally be 24 hours. Therefore consumer apps should always reuse the current token until they receive a 401 (Unauthorised) response from any endpoint at which time they should request a new token.

🚧

Do not request a new token for each API call. This may result in a 429 (Too many requests) response and result in the suspension of your API credentials/access.

Scope

The scope of a set of API credentials (client_id and client_secret) is limited to a single venue, per environment. For example if you have multiple ROLLER venues you must create separate sets of credentials for each venue, and credentials generated in the Playground environment will not work in Production.