User Based Authentication Guide

This guide will explain how to use the Buildr API to authenticate and authorize your application using the Authorization Code grant type.

​

Authorization Code Grant Type

The Authorization Code grant type is a secure and widely-used method of authorization that requires the user to explicitly grant access to your application.

​

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.

​

Request Flow

1. Redirect the user to the Buildr /oauth/authorize endpoint with the following query parameters:

   • response_type=code
   • client_id=your_client_id
   • redirect_uri=https://yourapp.com/redirect_uri
   • scope=read write

   Example:

   https://buildr.app/oauth/authorize?response_type=code&client_id=your_client_id&redirect_uri=https://yourapp.com/redirect_uri&scope=read%20write
   

2. The user will be prompted to authorize your application to access their Buildr data.

3. If the user approves your application, they will be redirected to your redirect URI with an authorization code as a query parameter. Example:

   https://yourapp.com/redirect_uri?code=your_authorization_code
   

​

Access Token Request

4. Your application should make a POST request to the Buildr /oauth/token endpoint with the following request body:

   {
     "grant_type": "authorization_code",
     "client_id": "your_client_id",
     "client_secret": "your_client_secret",
     "code": "your_authorization_code",
     "redirect_uri": "https://yourapp.com/redirect_uri"
   }
   

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

   {
     "access_token": "your_access_token",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "your_refresh_token",
     "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 a refresh token.

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

{
  "grant_type": "refresh_token",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "refresh_token": "your_refresh_token"
}

Buildr will respond with a new access token and refresh 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,
  "refresh_token": "your_new_refresh_token",
  "scope": "read write"
}

​

Conclusion

Congratulations! You have successfully authenticated and authorized your application with the Buildr API using the Authorization Code grant type. You can now use the access token to make requests to the Buildr API on behalf of the user.

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