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:
-
Cube creates an OAuth Application and provides a client ID used to authenticate with the API.
-
You login to the Cube Portal application to begin a valid session on the server.
-
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.
-
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 |
|
⬅ 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] |
|
|
⬅ Validates request and sends back OAuth access token and refresh token. Payload { |
Stores access_token and refresh_token then makes API requests using token inside Authorization header. Header Format 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:
-
Cube creates an OAuth Application and provides a client ID and secret used to authenticate with the API.
-
Your application uses the secure client ID and secret to obtain an authorization token from the Cube API.
-
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:
Client | Server |
Creates an authorization credential by concatenating client_id and client_secret and then base64-encoding the result. Pseudocode combined = client_id + ":" + client_secret |
|
Sends a POST to the /o/token/ endpoint to receive an authorization token using the credential in the Authorization header. Request Details Authorization: Basic [credential] |
|
⬅ Verifies that the credential supplied by the BasicAuthorization header is valid and sends back new OAuth access token and refresh token. Payload { |
|
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.
Client | Server |
Sends POST to /o/token/ endpoint. Payload client_id=[application client ID] |
|
⬅ Verifies that refresh token is valid and sends back new OAuth access token and refresh token. { |
|
Client stores new authentication data and uses it going forward for API calls and the eventual subsequent refresh of the token again. |
Comments
0 comments
Article is closed for comments.