Authentication

OAuth2

Authentication flow:

1. Perform OAuth2 Client Credentials authentication using API Credentials (client_id, client_secret) to obtain an access_token against /v1/oauth/token endpoint;
2. Use access_token as Bearer Authorisation for every other API request;
3. Include X-Client-Id (=client_id) within the header of every API request;
4. Note that some of the requests may also require a X-Customer-Id to be provided within the request header.

Examples

Obtain OAuth2 access_token and refresh_token using grant_type=client_credentials and HTTP Basic auth header

curl --basic --user {{client_id}}:{{client_secret}}  
  -X POST <https://api-sandbox.thisisbud.com/v1/oauth/token>  
  -H 'Content-Type: application/x-www-form-urlencoded'  
  -d grant_type=client_credentials

Successful response:

{  
  "operation_id": "oauth_token_post",  
  "data": {  
    "access_token": "dd0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff15",  
    "token_type": "bearer",  
    "expires_in": 3600,  
    "refresh_token": "fac32cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3"  
  }  
}

Refresh access_token token using refresh_token against /v1/oauth/token endpoint with grant_type=refresh_token

curl -X POST  
  <https://api-sandbox.thisisbud.com/v1/oauth/token>  
  -H 'Content-Type: application/x-www-form-urlencoded'  
  -H 'X-Client-Id: {{client_id}}'  
  -d 'grant_type=refresh_token&refresh_token={{refresh_token}}'

Successful response:

{  
    "operation_id": "oauth_token_post",  
    "data": {  
        "access_token": "cc0c17e3fd6d2ce94aa091257a3ea393b4f9b5cf3d3e998f07dc9826da86ff94",  
        "token_type": "bearer",  
        "expires_in": 3600,  
        "refresh_token": "ffc30cca7559d9f6e8f1dfe9a99c71fa1dcfeb482bedf287d7934d2667ae54b3"  
    }  
}

Best practice

In the /v1/oauth/token endpoint's response body Bud includes a expires_in attribute that defines the validity of the generated access token in seconds. It's important you cache the access_token on your architecture and re-use it for all the requests you'll send us for that period of time. This improves performance for all our endpoints as it guarantees a faster authorization process.

After the expires_in time is passed, you should generate a new access token by calling the create token endpoint again.

It's important to note that Bud doesn't guarantee that the access token will be valid for its entire life, so clients must have error handling in case of 401 errors on any endpoint request. When receiving a 401 http status response code for any of our endpoints, clients should create a new access token as described above and try the request again.

If you have any questions, please contact us via the chatbot (bottom-right of screen 👉) or via a support request or check our FAQs.