Get access to Bud API

Create a set of API Credentials

In order to successfully authenticate to Bud’s API services, you will first need to create a set of API credentials. This can be achieved from within the Bud Console. Follow this link to get Bud console access

The Bud Console allows you to manage your access to Bud's API services through the creation of different Projects.

👍

A Bud Project is set of API keys, so Project = API Keys

On the creation of a new project, you will be provided with an Client ID and Client Secret. Please store your Client Secret securely as you will be unable to retrieve it again from Bud.

Projects (aka API keys/credentials) are specific to the relevant Bud environment in which you are enrolled. If you are enrolled in more than a single Bud environment (e.g. Bud's Sandbox environment and Bud's Production environment), then you are able to toggle between these two environments within the Bud Console via a drop-down menu at the top of the right-hand side navigation bar (please note that this drop-down menu is not seen when enrolled into a single Bud environment). Projects can be created from within the Bud Console.

In addition, you are able to configure webhooks specific to a given Project. These webhooks are callback URLs, which must be configured in order to use some of Bud’s products and services.

📘

Please note that by default, all users are enrolled in Bud's Sandbox environment only. Bud's sandbox environment is a mirror or Bud's production environment, however, it only permits the use of dummy data.

Authenticate to Bud's API Services

Having acquired a set of API credentials from the developer console, the next step is to use them to obtain valid access and refresh tokens.

Authentication to Bud’s API services is made via OAuth2 protocol, whereby your API Credentials are used in exchange for a valid access_token and refresh_token. The access_token is valid for a limited amount of time (a maximum of one hour! although tokens can expire early), after which it will expire and you will then have to use the refresh_token or your API credentials in order to obtain a new one.

🚧

Token Expiration

Access tokens will last up to one hour, but they can also expire before that period of time has elapsed. It is important your application is resilient to handle token expiration.

We recommend that you implement logic such that if you ever receive a 401 or 403 on the Bud Platform, you attempt to retrieve a new access token before then retrying your API call as this likely indicates that the access token you are using has expired.

Access and refresh tokens are obtained via the POST /v1/oauth/token endpoint. Specify the grant_type as client_credentials within the request body and use HTTP Basic authentication within the request header. The basic authentication header is a base64 encoding of your API credentials, i.e. base64({client_id}:{client_secret}).

Example Access request (curl):

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"
  }
}

In order to obtain an access_token by using a valid refresh_token, simply make a request to the same endpoint but:

• replace the value of the grant_type field within the request payload to refresh_token;
• include the refresh_token within the payload under the key refresh_token;
• remove the basic authentication from request headers; and
• include your api-credentials-id within the request header under a key called X-Client-Id.

Example Refresh request (curl):

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"
    }
}

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