Authentication Course

This course explains how a user gets authenticated to access and use the GBDX APIs.

Related Documentation

Authentication Changes Announcement
Authentication FAQ
Get a Token
Validate a Token

Authentication Overview

GBDX uses token-based authentication for security. To get authenticated, a user must request a token, and then must include the token string when submitting an API request. This course explains how to get a token, and how to use it to make an API request.


AccountAn account can have many users. Users within an account can view and access data generated by other users within the account.
UserUsers are associated with accounts. Users have a unique username and password. All users have the same access to data within the account they're associated with.
TokenA token is a piece of data that includes all the information needed to authenticate a specific user. Users will use their account information to request a token. That token to allow the user access to the GDBX API endpoints.


Before we get started, there are a few things you should know about tokens.


You must have your user credentials to request a token. These credentials include:

  1. GBDX Username
  2. GBDX Password

Base URL

The base URL for API requests is


Your token gives you access to all GBDX API endpoints. It contains all the information needed to authenticate the user.

Token Expiration

Tokens have an expiration time of 7 days, or 604800 seconds. If your token expires, you will need to request a new one.

Get a Token

To get a token, send a POST request to the auth/v1/oauth/token/ endpoint.

See Get a Token to try it out.

The following information is required to use a token in an API request:

Headers"Authorization": "Bearer, "Content-Type": "application/json". "application/x-www-form-urlencoded" is also supported.
Parameters"grant_type": "password", "username": username, "password": password

The Get a Token request is included in the Postman Instructions & Collections .

JSON Response

A valid "Get a Token" request will return the following response:

       "access_token": <access token string>
       "scope": "openid email offline_access",
       "token_type": "Bearer",
       "expires_in": 604800,
       "refresh_token": <refresh token string>

Validate your Token

You can send a request to validate your token that will return a response with information about your token and account.

The URL for the Validate Token GET request is: /auth/v1/validate_token

The response to the Validate Token request is:

    "username": "USERS_NAME(this is typically the email address)",
    "user_id": "USER_ID",
    "account_id": "ACCOUNT_ID",
    "roles": ["ROLE"],
    "id": "USER_ID",
    "role": "ROLE",
    "is_super_user": false,
    "email": "USER_EMAIL",
    "account_level": "LEVEL"
Property NameValueMore Information
usernameGBDX user nameIn most cases, the username is the user's email address. A small set of legacy usernames are not email addresses.
user_idGBDX user IDThis is the identification number associated with the user.
account_idGBDX account IDthis is the identification number for the GBDX account the user is associated with.
rolesList of roles associated with the userAt this time, users can only have one role.
iduser IDThis field has the same value as the "user_id" field for backward compatibility.
rolethe role associated with the userThis field has the same value as the "roles" field. It has been retained for backward compatibility.
is_super_userTRUE/FALSE valueThis value is set to false unless the user has been granted "super user" permissions by GBDX.
emailThe email address the user entered when signing up for a GBDX accountFor most users, the "username" and "email" fields will have the same value.
account_levelGBDX account levelExamples: Basic

Error Codes

The authentication system returns conventional HTTP response codes to indicate success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate a server error.

Common errors returned by OAuth include:

Error CodeIssue
403Not authorized for this action
404Bad Content

Note: A 401: unauthorized error means that the user credentials are not valid or it could mean you need to get a token.

It will frequently mean one of the following:

  1. You have not signed the updated GBDX Terms of Service. To accept the new terms, sign into . If you have already signed, you won't be prompted. If you're not up to date, you'll be prompted to read and accept the terms.

  2. You have not verified your email address. New users receive an email that tells them how to verify their email address. If you didn't sign this, you won't be able to log in or use GBDX services. Contact [email protected] if you need assistance.

  3. You are not using the correct username or password. Username must be an email address.