Skip to main content

Cube API Authentication Flows

  • Updated

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.

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

Client Server
Logs in via standard login form.  
 

Establishes session and sends back session cookie.

Creates a code verifier (stores this locally for later use) and uses code verifier to create a code challenge.

Example: pkce-challenge

  

Sends GET to /o/authorize/ endpoint.

Parameters

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

⬅ Validates the user’s session and the code challenge then redirects the user to the resource specified by redirect URI with a code parameter appended to the query string.
Captures code from query string parameter.  

Sends POST to /o/token/ endpoint.

Payload

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
  

 

⬅ Validates request and sends back OAuth access token and refresh token.

Payload

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

Stores access_token and refresh_token then makes API requests using token inside Authorization header.

Header Format

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.

 

Related to

Related articles