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. Run the following to check that your credentials are set up correctly.

You can also pass it as the apiKey query parameter, as shown below.

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

If you are using an OAuth 2.0 access token, send it in the Authorization header.

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

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