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. (Parameter name “apiKey”)

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 

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" 
}