Cube API Authentication Flows

Cube authenticates with its API using OAuth standards and supports several methods for obtaining a token. Regardless of the method used, all requests to the Cube API must have an Authorization header containing a valid token. This document outlines the various OAuth methods supported by Cube and explains how to generate and use tokens created with those methods.

For broader documentation on Cube's API outside of authentication, see our docs.

General OAuth Flow

API endpoints require a valid authorization token for access. To obtain such a token using an OAuth flow, a client must follow these general steps:

• Authenticate with the Cube system to obtain an authorization token.

  • In the PKCE OAuth flow, users must login to Cube’s Portal application to identify themselves as valid.

• Exchange the authorization token for an OAuth token.

• Provide the OAuth token in the Authorization header on any request made to the Cube API.

• Refresh the auth token on an ongoing basis as specified by the API expiry.

PKCE Flow

PKCE (Proof Key for Code Exchange; pronounced “pixie”) extends the authorization flow to prevent CSRF and authorization code injection attacks. In the PKCE flow, the client creates a secret when making the initial authorization request, and then uses the secret again when exchanging the authorization code for an access token.

Initial setup:

1. Cube creates an OAuth Application and provides a client ID used to authenticate with the API.

2. You login to the Cube Portal application to begin a valid session on the server.

3. Your application performs the PKCE login flow, creating a code challenge, obtaining a code, and exchanging that code for an authorization token from the Cube API.

4. Your application passes the authorization token in the header of subsequent API requests, refreshing the token as needed.

Obtaining an Access Token via PKCE

Clients obtain an access token through the PKCE authentication flow below:

response_type=code
client_id=[application client ID]
redirect_uri=[redirect URI]
code_challenge=[generated from previous step]
code_challenge_method=S256

code=[from query string param]
client_id=[application client ID]
grant_type=authorization_code
redirect_uri=[valid redirect URI for your app]
code_verifier=[value from step 1 of flow]
scope=read write

{
    "access_token": "12345abcde",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write",
    "refresh_token": "6789xyz"
}

Authorization: Bearer 12345abcde

Refreshing an Access Token via PKCE

The token expires after a period of time, and the client needs to obtain a new one. The refresh flow is the same regardless of which original flow was used.

OAuth tokens expire in 10 hours (36000 seconds). Before that time expires, clients should exchange their refresh token for a new access token to extend their access.