API Authentication

Overview

All requests to the Bloom API require a valid Oauth2 Access Token to be present in the Authorization header. You can think of this Access Token like an API key, it is what grants you access to the API.

Bloom will provide you with two credentials:

(1) Client ID
and
(2) Client Secret

These two credentials are what you will use to request an Access Token. You will do so using the Oauth2 client_credentials grant flow which will be explained below.

While your provided Client ID is considered a "public" credential, your Client Secret must only be known by your backend application(s). It must never be included in any front-end applications, stored in plaintext, or transmitted across unsecured (non-SSL) connections. Treat it as you would a password.

Keep your credentials safe!

If at any time you believe your credentials may have been compromised, please let Bloom know immediately so we can rotate them for you.

General Flow

You will gain and maintain access to the API with the following flow:

1. Use your Client ID and Client Secret to fetch an Access Token
2. Put the Access Token in the Authorization header of any request you make to the Bloom API
3. When the token expires fetch a new one and go back to step (2)

1. Retrieving an Access Token

Make a POST request to the /oauth/token endpoint of the authorization URL.

Use the Environments concept page to find the authorization URL that corresponds to your target environment.

Required Parameters

💡 Quick tip

Click the Code Generation tab below to get see an example of this request in your language of choice.

{
  "method": "post",
  "url": "https://auth.bloom.dev/oauth/token",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": {
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "audience": "<API_ENVIRONMENT_AUDIENCE>",
    "grant_type": "client_credentials"
  }
}

{
    "access_token": "<ACCESS_TOKEN_WILL_BE_HERE>",
    "scope": "read:consumers write:consumers read:credit.bloom.score.vantage3...",
    "expires_in": 86400,
    "token_type": "Bearer"
}

️⚠️ Caching Access Tokens

Please note that when requesting access tokens using your client credentials, your application should use the access token until it expires. The Access Token Response includes an expires_in field which you can use to determine if the token needs to be renewed (this field contains the number of seconds from when the token was created to when it will expire).

If the token is expired, you can issue a new POST request to /oauth/token to receive a new access token as you normally would for new tokens.

In the future, we may limit the number of new access tokens granted within a given period of time and caching tokens will ensure you are set up for optimizing the usage of our API with a single access token.

2. Making API Requests

Now that you have successfully fetched an Access Token, you can make requests to the rest of the Bloom API. Simply add an HTTP Authorization header in the following format to any request you make to the Bloom API:

"Authorization: Bearer <ACCESS_TOKEN>"