## 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  
### Using Auth V2 Endpoint  
Make a `POST` request to the `/oauth2/token` endpoint of the authorization URL.

> 🚧
> ### Content Type Restriction  
> Please note that Auth V2 endpoint strictly follows original OAuth 2.0 specification (RFC 6749), and thus for maximum compatibility only supports content-type: application/x-www-form-urlencoded. Please refer below examples.

#### Required Parameters  
| Parameter        | Value                                                                                                                                                                      |
|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `client_id`     | Your **Client ID**                                                                                                                                                         |
| `client_secret` | Your **Client Secret**                                                                                                                                                     |
| `audience`      | See the<br>[Environments](https://developers.bloomcredit.io/docs/environments-1#per-environment-parameters)<br>concept page to find the audience that corresponds to your target environment |
| `scope`         | Space separated scopes as required to access api endpoints.<br>Set "data-access:all"for Data Access endpoints.<br>Set "furnishment:all"for Furnishment endpoints.<br>Set "bloomplus:all"for Enablement Services endpoints.<br>Set "data-access:all furnishment:all bloomplus:all"for Data Access, Furnishment, and Enablement Services endpoints.  |
| `grant_type`    | Always use `client_credentials`                                                                                                                                           |

```json
{
  "method": "post",
  "url": "https://authn.bloomcredit.dev/oauth2/token",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  "body": {
    "client_id": "<CLIENT_ID>",
    "client_secret": "<CLIENT_SECRET>",
    "audience": "<API_ENVIRONMENT_AUDIENCE>",
    "scope": "<SCOPES_REQUIRED_PER_API_ENDPOINT>",
    "grant_type": "client_credentials"
  }
}
```

#### Access Token Response:
Most commonly you should expect to see 200 status code or a 401 status code. The default error schema let's you handle any unexpected errors like 500 internal server error. If you encounter any other errors, please reach out to us.

```json
{
    "access_token": "<ACCESS_TOKEN_WILL_BE_HERE>",
    "scope": "data-access:all furnishment:all bloomplus:all",
    "expires_in": 86400,
    "token_type": "Bearer"
}
```

```json
{
    "error": "string",
    "error_description": "string"
}
```

```json
{
    "error": "invalid_client",
    "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method). passwords do not match"
}
```

> 🚧
> ### 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).

## 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>"`

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