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 create a new app using our API go to your Buddy account settings to create Apps, or click on your avatar in the top right corner → select Apps from the menu.

In the Apps tab you will find the list of your apps, click + to add a new app.

Image loading...

A new window will show up asking you to fill the following fields:

After saving the form, you will receive the application's authentication credentials:

• Client ID - the public identifier of your app.
• Client Secret - a confidential key required for authentication.

Image loading...

Save this information in a secure place immediately, as the secret will no longer be available after closing the popup. If you lose the Client Secret, you can reset it in the application settings.

Image loading...

Web application flow

1. Redirecting user to address to gain access

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

example:

https://api.buddy.works/oauth2/authorize?type=web_server&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&response_type=code&scope=<SCOPE>&state=<STATE>

GET Parameters

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

Image loading...

2. Receiving authentication code

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

https://<REDIRECT_URI>?code=<CODE>&state=<STATE>

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

example:

curl
curl --request POST https://api.buddy.works/oauth2/token \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=authorization_code&code=<CODE>&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=<REDIRECT_URI>"

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.

OAuth app management

After registering and deploying the OAuth application, you may need to manage its credentials or user access.

Authorized apps

The "Authorized OAuth apps" section shows which applications have gained access to your Buddy account.

Image loading...

Resetting the Client Secret

If your Client Secret has been exposed or you don't remember it, you can reset it in the application settings.

Note: The old secret will stop working immediately and cannot be restored.

Revoking all user tokens

To force all users of the application to reauthorize (e.g., after a security incident), you can revoke all user tokens.

Warning: This action is immediate and irreversible.

Supported scopes