Machine Based Authentication Guide

If you are developing an application or integration that does not rely on or require access authorization from a specific Buildr user, then you will want to implement the Client Credentials grant type. The Client Credentials grant type is often used for machine-to-machine based integrations that aren’t user specific.

​

Client Credentials Grant Type

The Client Credentials grant type is a simple, non-interactive way to obtain an access token that can be used to make authorized API requests on behalf of your application. This grant type uses a client ID and client secret to authenticate with the Buildr API.

​

Scopes

Buildr uses scopes to control access to different parts of the API. The two available scopes for the Client Credentials grant type are read and write. If you want to read and write, you need to request both scopes.

• read Allows read access to the Buildr API.
• write Allows write access to the Buildr API.

​

Access Token Request

1. Make a POST request to the Buildr /oauth/token endpoint with the following request body:

   {
     "grant_type": "client_credentials",
     "client_id": "your_client_id",
     "client_secret": "your_client_secret",
     "scope": "read write"
   }
   

2. Buildr will respond with a JSON object containing an access token and information about the token’s expiration time. Example response:

   {
     "access_token": "your_access_token",
     "token_type": "Bearer",
     "expires_in": 3600,
     "scope": "read write"
   }
   

​

Refreshing Access Tokens

Access tokens have a limited lifespan and will eventually expire. When this happens, your application must obtain a new access token using the same client credentials.

To refresh an access token, make a POST request to the Buildr /oauth/token endpoint with the following request body:

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Buildr will respond with a new access token, as well as information about the token’s expiration time. Example response:

{
  "access_token": "your_new_access_token",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

​

Conclusion

Congratulations! You have successfully obtained an access token using the Client Credentials grant type. You can now use the access token to make requests to the Buildr API on behalf of your application.

Please note that these are just examples and the actual responses may differ depending on your Buildr integration configuration.