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.


Term Definition
Account An account can have many users. Users within an account can view and access data generated by other users within the account.
User Users 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.
Token A 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:

Name Description
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 Name Value More Information
username GBDX user name In most cases, the username is the user's email address. A small set of legacy usernames are not email addresses.
user_id GBDX user ID This is the identification number associated with the user.
account_id GBDX account ID this is the identification number for the GBDX account the user is associated with.
roles List of roles associated with the user At this time, users can only have one role.
id user ID This field has the same value as the "user_id" field for backward compatibility.
role the role associated with the user This field has the same value as the "roles" field. It has been retained for backward compatibility.
is_super_user TRUE/FALSE value This value is set to false unless the user has been granted "super user" permissions by GBDX.
email The email address the user entered when signing up for a GBDX account For most users, the "username" and "email" fields will have the same value.
account_level GBDX account level Examples: 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 Code Issue
401 Unauthorized
403 Not authorized for this action
404 Bad 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.

Updated 6 months ago

Authentication Course

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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.