Authentication

Your application is required to authenticate through our authorization API for accessing the Bliss APIs.

For Bliss APIs to process requests, it's mandatory to include an Authentication header with a valid access token, which can be acquired using client credentials. To obtain this token, submit a request with your API keys to our authorization API.

Before you begin, it's essential to connect with our sales team to set up a guarantee policy (or multiple guarantee policies) for enrolling your clients. We provide a Sandbox environment for testing purposes before you transition to our Production environment. In each environment, Bliss will supply you with two distinct identifiers:

• client id, a client id provided by Bliss.
• client secret, a client secret provided by Bliss.

Handle the client id and secret with the utmost confidentiality, similar to how you would manage a username and password. Adhere to robust security practices with these credentials. It's advisable to integrate these values into your runtime environment securely, ensuring they are not stored in any source code repositories.

Bliss offers an API endpoint for exchanging your client id and secret for a temporary access token. This endpoint accepts a POST request with a JSON-encoded body containing two string fields (client_id and client_secret). For instance, you can use the following curl command to send a request to our sandbox API:

curl --request POST \
     --url https://api.sandbox.blissguarantee.com/api/oauth/token \
     --header 'content-type: application/json' \
     --data '
{
  "client_id": "your_client_id_here",
  "client_secret": "your_client_secret_here"
}
'

If the given client_id and client_secret are valid, the response will look something like the following:

{  
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",  
  "expires_in": 86400,  
  "token_type": "Bearer"  
}

The authorization endpoint's response includes an expires_in field, indicating the token's validity period in seconds (typically 24 hours by default). We suggest caching the token post-retrieval to minimize request frequency. Set your cache's expiration slightly earlier than the token's actual expiry time as a precaution.

The API returns a 401: Unauthorized error when the token expires. A new token is required to complete the API request.

📘

Note: only request a new token when your existing token has expired or is about to expire

Notice the token_type in the response is Bearer, and the expires_in field will indicate the number of seconds for which the token is valid. The access_token field contains the value that you will subsequently pass to our API endpoints in the Authorization header of your request. You may now utilize this token to issue a request. For example, to retrieve a previously submitted enrollment by id, issue the following curl command:

curl --request GET  
     --url <https://api.sandbox.blissguarantee.com/api/v1/enrollments/>\<a_previously_generated_id_here>
     --header 'Accept: application/json'  
     --header 'Authorization: Bearer \<your_access_token_here>'