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

Success
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:

Image loading...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 create an ne w 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...Empty OAuth apps dashboard

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

Name Description
application 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.
application description The description displayed to all users of your application.
logo The logo displayed on your application list.

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...OAuth app view with client secret reveal modal

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].(#resetowanie-client-secret).

Image loading...Copy client secret dialog in OAuth 2.0 app settings

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

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
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 access for your app with the required scopes.

Image loading...Authorization prompt for OAuth app requesting access to user information

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>
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.

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

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:

json
{ "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:

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

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.

Success
  • 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

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...OAuth apps panel

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

Name Description
Workspace scopes
WORKSPACE Access to basic workspace information as well as the rights to manage members, groups and member permissions
PROJECT_DELETE Permission to delete projects.
MEMBER_EMAIL Access to contact info of workspace members.
MANAGE_EMAILS Permission to view and manage user email addresses (contains USER_EMAIL rights).
Repository scopes
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).
Pipelines scopes
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).
Environment scopes
ENVIRONMENT_INFO Access to environment info.
ENVIRONMENT_ADD Permission to get and add environment.
ENVIRONMENT_MANAGE Permission to add/edit and delete environment.
Target scopes
TARGET_INFO Access to target info.
TARGET_ADD Permission to get and add target.
TARGET_MANAGE Permission to add/edit and delete target.
Domain scopes
ZONE_READ Access to the domains info.
ZONE_WRITE Permission to add/edit/delete domain's records.
ZONE_MANAGE Permission to manage domains.
Webhook scopes
WEBHOOK_INFO Access to webhooks info.
WEBHOOK_ADD Permission to get and add webhooks.
WEBHOOK_MANAGE Permission to add/edit and delete webhooks.
Variable scopes
VARIABLE_INFO Access to environment variables' info.
VARIABLE_ADD Permission to get and add environment variables.
VARIABLE_MANAGE Permission to add/edit and delete environment variables.
User scopes
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.
Integrations scopes
INTEGRATION_INFO Access to the list of integrations available to the authorized user.
INTEGRATION_ADD Permission to get and add integrations.
INTEGRATION_MANAGE Permission to manage integrations.
Tokens scopes
TOKEN_INFO Access to personal access tokens info.
TOKEN_MANAGE Permission to add and delete personal access tokens.

Last modified on May 20, 2025