Authentication & Authorization

API Key

The API key allows you make requests to the Backlog API.

Append your API key to requests to the API to return data from your account. (Parameter name "apiKey")

Request Example

https://xx.backlogtool.com/api/v2/users/myself?apiKey=abcdefghijklmn

Issue an API key via Personal Settings > API Settings page.

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 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 authorize your application.

Form parameters

Name Type Description
response_type (Required) String Fixed "code"
client_id (Required) String
redirect_uri String
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 String Required if you specify redirect_uri in authorization request
client_id (Required) String
client_secret (Required) String

Response Example

HTTP/1.1 200 OK
Content-Type:application/json;charset=utf-8
{
    "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.jp
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

HTTP/1.1 200 OK
Content-Type:application/json;charset=utf-8
{
    "access_token": "YOUR_ACCESS_TOKEN",
    "token_type":"Bearer",
    "expires_in":3600,
    "refresh_token":"YOUR_REFRESH_TOKEN"
}