Contents

Getting Started

This page shows how to start using the Backlog API. If you just want to try it quickly, follow the steps below in order.

1. Prepare to use the Backlog API

To use the Backlog API you need either an API key or an OAuth 2.0 access token.

  • API key — the easiest way. Log in to your Backlog space and issue a key from Personal Settings > API.
  • OAuth 2.0 — recommended when your application accesses the API on behalf of other Backlog users. Register your application on the Backlog Developer Site to obtain a client_id and client_secret.

See Authentication & Authorization for the full details.

2. Send your first request

Now let’s send a request. The /api/v2/users/myself endpoint returns the authenticated user.

Using an API key

Send your API key in the Backlog-API-Key request header. Run the following command to check that your credentials are set up correctly.

curl -H "Backlog-API-Key: YOUR_API_KEY" \
  "https://{{YOUR-DOMAIN}}/api/v2/users/myself"

Replace the following placeholders with your own values:

  • {{YOUR-DOMAIN}}: your space domain
  • YOUR_API_KEY: the API key you issued in step 1

Your space domain is one of the following:

  • [Space ID].backlog.com
  • [Space ID].backlog.jp
  • [Space ID].backlogtool.com

If you don’t know your Space ID, see Space ID.

You can also send the API key as the apiKey query parameter. However, an API key included in the URL may be recorded in access logs or browser history. We recommend sending it in the request header.

curl "https://{{YOUR-DOMAIN}}/api/v2/users/myself?apiKey=YOUR_API_KEY"

Using an OAuth 2.0 access token

Send your access token in the Authorization header. Run the following command to check that your credentials are set up correctly.

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  "https://{{YOUR-DOMAIN}}/api/v2/users/myself"

Replace YOUR_ACCESS_TOKEN with the access token you obtained.

3. Check the response

On success

On success, the API returns HTTP 200 OK along with the authenticated user’s information as JSON.

{
  "id": 1,
  "userId": "admin",
  "name": "admin",
  "roleType": 1,
  "lang": "en",
  "mailAddress": "admin@example.com"
}

On failure

On failure, the API returns a 4xx or 5xx status code along with a JSON body containing an errors array.

{
  "errors": [
    {
      "message": "Authentication failure.",
      "code": 11,
      "moreInfo": ""
    }
  ]
}

OAuth 2.0 authentication failures are the exception: they return a 401 status code with the error details in the WWW-Authenticate response header instead of the errors JSON body. See Authentication & Authorization for details.

Common causes:

  • The API key is wrong or belongs to a different space — check the domain in the URL.
  • The access token has expired — refresh it. See Authentication & Authorization.

See Error Response for the full list of error codes.

Next steps