Introduction
Buddy API uses OAuth 2.0 for authentication. OAuth2 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.
To start developing, you need to add the application in your profile
The following data is required:
| Name | Description | |
|---|---|---|
name Required | ||
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 | ||
| logo |
Upon adding, the application will contain the Client ID and 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 | 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 | State posted before. Must be the same as original. If it’s not the same, the authentication process should be cancelled. |
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 | 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 was included in the authorization request as described in this section, and 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 the following 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 | List of scopes; divided with space |
Authentication Response
In response to method POST https://api.buddy.works/oauth2/token you’ll receive:JSON
{"access_token" : "732e9e20-50ba-4047-8a7b-c9b17259a2a2","token_type" : "Bearer"}
| Name | Type | Description |
|---|---|---|
| access_token | String | Token used to authenticate requests in API. |
| token_type | String | Type of token (at the moment only bearer is supported by Buddy). |
The returned token is used to authenticate when invoking API methods. Keep in mind that tokens in Buddy never expire.
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. |
GitHub
Bitbucket
Email