> For the complete documentation index, see [llms.txt](https://developers.bloomcredit.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bloomcredit.io/reference/v2.1/core/readme.md). # 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. {% hint style="warning" %} **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. {% endhint %} ## 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. {% hint style="warning" %} **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. {% endhint %} #### Required Parameters | Parameter | Value | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | Your **Client ID** | | `client_secret` | Your **Client Secret** | | `audience` | See the [Environments](/docs/v2.1/getting-started/environments.md#per-environment-parameters) concept page to find the audience that corresponds to your target environment | | `scope` | Space separated scopes as required to access api endpoints. Set `"data-access:all"`for Data Access endpoints. Set `"furnishment:all"`for Furnishment endpoints. Set `"bloomplus:all"`for Enablement Services endpoints. Set `"data-access:all furnishment:all bloomplus:all"`for Data Access, Furnishment, and Enablement Services endpoints. | | `grant_type` | Always use `client_credentials` | {% hint style="info" %} **Quick tip** Click the **Code Generation** tab below to get see an example of this request in your language of choice. {% endhint %} {% tabs %} {% tab title="http" %} ```json { "method": "post", "url": "https://authn.bloomcredit.dev/oauth2/token", "headers": { "Content-Type": "application/x-www-form-urlencoded" }, "body": { "client_id": "", "client_secret": "", "audience": "", "scope": "", "grant_type": "client_credentials" } } ``` {% endtab %} {% tab title="cURL" %} ```php curl --location --request POST 'https://authn.bloomcredit.dev/oauth2/token' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'client_id=$CLIENT_ID' \ --data-urlencode 'client_secret=$CLIENT_SECRET' \ --data-urlencode 'audience=$AUDIENCE' \ --data-urlencode 'scope=$SCOPE' \ --data-urlencode 'grant_type=client_credentials' ``` {% endtab %} {% tab title="JS - Fetch" %} ```javascript var myHeaders = new Headers(); myHeaders.append("Content-Type", "application/x-www-form-urlencoded"); var urlencoded = new URLSearchParams(); urlencoded.append("client_id", "$CLIENT_ID"); urlencoded.append("client_secret", "$CLIENT_SECRET"); urlencoded.append("audience", "$AUDIENCE"); urlencoded.append("scope", "$SCOPE"); urlencoded.append("grant_type", "client_credentials"); var requestOptions = { method: 'POST', headers: myHeaders, body: urlencoded, redirect: 'follow' }; fetch("https://authn.bloomcredit.dev/oauth2/token", requestOptions) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.log('error', error)); ``` {% endtab %} {% tab title="Python - Requests" %} ```python import requests url = "https://authn.bloomcredit.dev/oauth2/token" client_id = "$CLIENT_ID" client_secret = "$CLIENT_SECRET" audience = "$AUDIENCE" scope = "$SCOPE" payload= f'client_id={client_id}&client_secret={client_secret}&audience={audience}&scope={scope}&grant_type=client_credentials' headers = { 'Content-Type': 'application/x-www-form-urlencoded' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` {% endtab %} {% tab title="Node.js" %} ```javascript var https = require('follow-redirects').https; var fs = require('fs'); var qs = require('querystring'); var options = { 'method': 'POST', 'hostname': 'authn.bloomcredit.dev', 'path': '/oauth2/token', 'headers': { 'Content-Type': 'application/x-www-form-urlencoded' }, 'maxRedirects': 20 }; var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); var postData = qs.stringify({ 'client_id': '$CLIENT_ID', 'client_secret': '$CLIENT_SECRET', 'audience': '$AUDIENCE', 'scope': '$SCOPE', 'grant_type': 'client_credentials' }); req.write(postData); req.end(); ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "strings" "net/http" "io/ioutil" ) func main() { url := "https://authn.bloomcredit.dev/oauth2/token" method := "POST" payload := strings.NewReader("client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&audience=$AUDIENCE&scope=$SCOPE&grant_type=client_credentials") client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("Content-Type", "application/x-www-form-urlencoded") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := ioutil.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} #### 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. {% tabs %} {% tab title="JSON - 200 success" %} ```json { "access_token": "", "scope": "data-access:all furnishment:all bloomplus:all", "expires_in": 86400, "token_type": "Bearer" } ``` {% endtab %} {% tab title="JSON - default error schema" %} ```json { "error": "string", "error_description": "string" } ``` {% endtab %} {% tab title="JSON - 401 unauthorized example" %} ```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" } ``` {% endtab %} {% endtabs %} {% hint style="warning" %} **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 `/oauth2/token` to receive a new access token as you normally would for new tokens. {% endhint %} ## 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 "`
{% code title="JSON" %} ```json { "access_token": "", "scope": "read:consumers write:consumers read:credit.bloom.score.vantage3...", "expires_in": 86400, "token_type": "Bearer" } ``` {% endcode %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.bloomcredit.io/reference/v2.1/core/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.