Cube API Authentication Flows

Cube uses authentication methods based on OAuth standards to handle authenticating with its API 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.

  • In the Client Credentials flow, the client uses an ID and a secret to obtain an authorization token.

• 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.

In general, which flow works for you generally depends on your use case:

• PKCE: Helpful if you are building an interactive app where users will be logging in and interacting with Cube in that way
• Client Credentials: Likely best when building a service to consume the API that won't have much user interaction

Both flows will require a client ID tied to an OAuth application. To get a client ID ask your CSM at Cube to get a request in to the Engineering team.

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

Client Credentials Flow

The Client Credentials flow works best for connecting applications to the Cube API and allows machines to obtain authorization tokens using secure credentials. When using the Client Credentials flow, the Client ID and Client Secret must be kept secure as they can be used to login on your behalf!

Initial setup:

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

2. Your application uses the secure client ID and secret to obtain an authorization token from the Cube API.

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

Obtaining an Access Token via the Client Credentials Flow

Clients can obtain an access token when specifying client credentials using the following steps:

combined = client_id + ":" + client_secret
credential = base64(combined)

Authorization: Basic [credential]

grant_type=client_credentials

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

Authorization: Bearer 12345abcde

Refreshing an Access Token via PKCE

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

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

client_id=[application client ID]
grant_type=refresh_token
refresh_token=[original refresh token]

{
    "access_token": "some-new-token",
    "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "read write",
    "refresh_token": "also-new-token"
}