Authentication & Authorization
API Key
The API key allows you make requests to the Backlog API.
Append your API key to the API requests to return data from your account. The API key can be sent as the query parameter “apiKey” or as the request header “Backlog-API-Key”.
Request Example
https://xx.backlog.com/api/v2/users/myself?apiKey=abcdefghijklmn
If the URL is backlogtool.com it will look like the example below.
https://xx.backlogtool.com/api/v2/users/myself?apiKey=abcdefghijklmn
Request Example (Request Header)
You can also send your API key in the “Backlog-API-Key” request header instead of the query parameter.
GET /api/v2/users/myself
HTTP/1.1
Host: xx.backlog.com (If the URL is backlogtool.com, it will be xx.backlogtool.com)
Backlog-API-Key: abcdefghijklmn
OAuth 2.0
You can access the Backlog API by using the “Authorization Code Grant” defined in “The OAuth 2.0 Authorization Framework” (RFC 6749).
Register your application in the Backlog Developer Site first to obtain your client_id and client_secret.
Authorization Request
Method
GET
URL
/OAuth2AccessRequest.action
This is an authorization endpoint URI. Backlog calls redirect_uri with an authorization code if a user authorizes your application.
Form parameters
| Name | Type | Description |
|---|---|---|
| response_type (Required) | String | Fixed “code” |
| client_id (Required) | String | |
| redirect_uri (Required) | String | The same URI you set on the Developer Application page |
| state | String |
Access Token Request
Method
POST
URL
/api/v2/oauth2/token
This is a token endpoint URI. You can get a valid access token and refresh token by using an authorization code. The authorization code is shown in the redirected request that Backlog calls.
Form parameters
Content-Type:application/x-www-form-urlencoded
| Name | Type | Description |
|---|---|---|
| grant_type (Required) | String | Fixed “authorization_code” |
| code (Required) | String | authorization code that you get from redirected request Backlog calls |
| redirect_uri (Required) | String | The same URI you set on the Developer Application page |
| client_id (Required) | String | |
| client_secret (Required) | String |
Response example
Status Line / Response Header
HTTP/1.1 200 OK
Content-Type:application/json;charset=utf-8
Response Body
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"YOUR_REFRESH_TOKEN"
}
API Access with Access Token
You can call Backlog API using the access token in the “Authorization” header.
GET /api/v2/space
HTTP/1.1
Host: example.backlog.com (If the URL is backlogtool.com, it will be example.backlogtool.com)
Authorization: Bearer YOUR_ACCESS_TOKEN
Authentication failure may return status code 401. The error message can be found in the WWW-Authenticate header.
- Access token is invalid
"Bearer error="invalid_token", error_description="The access token is invalid"
- Access token is expired
"Bearer error="invalid_token", error_description="The access token expired"
Refresh Access Token
An access token expires in 3600 seconds (1 hour). You can get a new access token by using your refresh token.
Method
POST
URL
/api/v2/oauth2/token
Form parameters
Content-Type:application/x-www-form-urlencoded
| Name | Type | Description |
|---|---|---|
| grant_type (Required) | String | Fixed “refresh_token” |
| client_id (Required) | String | |
| client_secret (Required) | String | |
| refresh_token (Required) | String |
Response example
Status Line / Response Header
HTTP/1.1 200 OK
Content-Type:application/json;charset=utf-8
Response Body
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"YOUR_REFRESH_TOKEN"
}
Permission and Restriction
Whether a user can call an API is determined by the combination of that user’s permission and restriction. See User roles and privileges for what each of them allows.
Permission
The role a user holds in a space or a project.
- Administrator
- Project Administrator
- Member
- Guest
On API pages, “All permissions” means all four of the above.
Restriction
A setting that narrows down what a user can do within the range of their permission. It can be set for Member and Guest.
- No restriction
- Add issue only
- View only
How to read the Role section
Each API page lists the users who can call that API under Role. It is written in the following patterns.
When permission and restriction are both listed
A user can call the API if they match one of the values listed in each of the Permission and Restriction blocks. Where a block lists several values, matching any one of them is enough.
For example, Post Attachment File lists “All permissions” as the permission, and “Add issue only” and “No restriction” as the restriction. This API can be called regardless of permission, as long as the restriction is either “Add issue only” or “No restriction”. A user restricted to “View only” cannot call it.
When only permissions are listed
Where permissions such as “Administrator” or “Project Administrator” are listed on their own, a user holding one of those permissions can call the API. Where several values are listed, matching any one of them is enough.
When only “All” is listed
Every user can call the API, whatever their permission and restriction.
This is not the same as “All permissions” in a Permission block. “All permissions” means the permission does not matter, and the Restriction block still narrows down who can call the API. “All” on its own applies no restriction condition at all.