Introduction to OAuth 2.0

Table of Contents

March 2022 update Creating new OAuth app Web application flow 1. Redirecting user to address to gain access 2. Receiving authentication code 3. Exchanging code for access token Basic authorization Authentication response Refreshing tokens Supported scopes

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

To increase security, from March 29, 2022, the tokens in newly created applications automatically expire after 8 hours.

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:

Deprecation notice

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:

Name	Description
name `Required`	The application name displayed in Buddy.
homepage URL `Required`	The full URL to your application homepage.
authorization callback URL `Required`	The URL in your app where users will be sent after authorization.
description	The description displayed to all users of your application.
logo	The logo displayed on your application list.

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

Name	Type	Description
type `Required`	String	Must be set to `web_server`.
client_id `Required`	String	Client ID. Received when registering the app.
redirect_uri	String	The redirect_uri parameter is optional. If left out, Buddy will redirect users to the callback URL configured in the OAuth Application settings. If provided, the redirect URL’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL.
response_type `Required`	String	Must be set to `code`.
scope `Required`	String	The list of scopes; divided with `+` character.
state	String	An unguessable random string. It is used to protect against cross-site request forgery attacks.

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:

Name	Type	Description
code	String	To be exchanged for access token in the next step.
state	String	The state posted before. Must be the same as original. If it’s not the same, you should cancel the authentication process.

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

Name	Type	Description
code `Required`	String	The code that you received in the previous step.
client_id `Required`	String	Client ID; received during app registration.
client_secret `Required`	String	Client Secret; received during app registration.
redirect_uri	String	IMPORTANT: This param is required if the `redirect_uri` parameter is included in the authorization request (as described in this section). Their values must be identical.
grant_type `Required`	String	Must be set to `authorization_code`.

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

Name	Type	Description
grant_type `Required`	String	Must be set to `client_credentials`.
scope `Required`	String	The list of scopes; divided with space

Authentication response

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

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

Name	Type	Description
access_token	String	The token used to authenticate the requests in the API.
expires_in	int	The number of seconds in which the access token expires.
refresh_token	String	Required to refresh the access token once it expires.
refresh_token_expires_in	int	The number of seconds in which the refresh token expires.
token_type	String	The type of the token (at the moment only bearer is supported by Buddy).

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:

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

Name	Type	Description
refresh_token	String	The refresh token that you received with the previous token.
client_id `Required`	String	Client ID; received during app registration.
client_secret `Required`	String	Client Secret; received during app registration.
grant_type `Required`	String	Must be set to `refresh_token`.

You will receive the following response.

Refresh tokens are valid for 6 months.
A token can be refreshed even if it has not yet expired.
The refresh invalidates the current access_token and refresh_token

Supported scopes

Name	Description
WORKSPACE	Access to basic workspace information as well as the rights to manage members, groups and member permissions
PROJECT_DELETE	Permission to delete projects.
REPOSITORY_READ	Access to commits and repository content. Repository checkout is allowed, too.
REPOSITORY_WRITE	Permission to write in the repository. File deletion is allowed, too (contains `REPOSITORY_READ` rights).
EXECUTION_INFO	Access to executions history.
EXECUTION_RUN	Permission to run and stop executions (contains `EXECUTION_INFO` rights).
EXECUTION_MANAGE	Permission to add/edit pipelines (contains `EXECUTION_RUN` rights).
USER_INFO	Access to base information of the authorized user.
USER_KEY	Access to public SSH keys of authorized user.
USER_EMAIL	Access to email list of authorized user.
INTEGRATION_INFO	Access to integration list of authorized user.
MEMBER_EMAIL	Access to contact info of workspace members.
MANAGE_EMAILS	Permission to view and mange user email addresses (contains `USER_EMAIL` rights).
WEBHOOK_INFO	Access to webhooks info.
WEBHOOK_ADD	Permission to get and add webhooks.
WEBHOOK_MANAGE	Permission to add/edit and delete webhooks.
VARIABLE_ADD	Permission to get and add environment variables.
VARIABLE_INFO	Access to environment variables' info.
VARIABLE_MANAGE	Permission to add/edit and delete environment variables.