Introduction to OAuth 2.0

Buddy API uses OAuth 2.0 for authentication. OAuth 2.0 is a protocol that lets external apps request authorization to private details in the user’s data without getting his password. Tokens can be limited to specific types of data, and can be revoked by users at any time. All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.

March 2022 update

In the old applications, the tokens never expire (just as they did before). If your app uses the old type of tokens, you will see this notice on the application screen:

Image loading...

Expired tokens can be regenerated using the refresh token. Tokens regenerated for the old type of apps also come with the refresh token, even though they do not expire.

Creating new OAuth app

To start developing, you need to add the application in your profile. The following data is required:

Upon adding, the application will contain the Client ID and the Client Secret required for further steps.

Web application flow

1. Redirecting user to address to gain access

GET https://api.buddy.works/oauth2/authorize

GET Parameters

The user will receive a website with login form to your Buddy workspace. In the next step he can either allow or revoke access for your app with the required scopes.

2. Receiving authentication code

If the user accepts your application, he gets redirected to redirect_uri (see previous step) with two parameters:

3. Exchanging code for access token

In the next step, you need to send the code in the following request:

POST https://api.buddy.works/oauth2/token

Content-Type: application/x-www-form-urlencoded

POST Parameters

You will receive the following response.

Basic authorization

Authorization is used mainly to test the app by a developer. Only the app developer may authenticate. To retrieve the access token, you need to execute this request:

POST https://api.buddy.works/oauth2/token

Attach this HTTP header:

'Authorization: Basic ' + base64(client_id + ':' + client_secret)

POST Parameters

Authentication response

The method POST https://api.buddy.works/oauth2/token will produce a response like this:

json
{
    "access_token": "732e9e20-50ba-4047-8a7b-c9b17259a2a2",
    "expires_in": 28800,
    "refresh_token": "p8gUgmrXwe5CT2TMiMMkpIIRlIMlH70aB19dxwGJJkNWp4LthWUjJDmmUmBd7xLPzDq8R5PtCvx0SvAS",
    "refresh_token_expires_in": 158112000,
    "token_type": "Bearer"
}

Refreshing tokens

The returned token is used to authenticate when invoking API methods. Keep in mind that tokens created in Buddy before March 29, 2022, never expire. Tokens generated after that date expire in 8 hours from the creation.

If the token expires, the request to the API will return the following response:

json
401 Unauthorized
{
  "errors": [
    {
      "message": "Wrong authentication data"
    }
  ]
}

In such case, you need to run this request to refresh it:

POST https://api.buddy.works/oauth2/token

Content-Type: application/x-www-form-urlencoded

POST Parameters

You will receive the following response.

Supported scopes