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