PolderAPI

Getting started

Authentication

Create an API token, send it as a bearer token and keep it safe.

The Backlog API is authenticated by a bearer token and nothing else. There is no cookie fallback: a request that arrives with a browser session is not treated as an API client, and the other way around.

Authorization: Bearer <token>
Accept: application/json

Tip Always send Accept: application/json. Without it, an error such as a missing token can come back as a redirect to the sign-in page instead of a JSON body.

Create a token

  1. In Backlog, open Settings → API tokens.
  2. Give the token a name that says what uses it (deploy-bot, report-dashboard).
  3. Tick the scopes it needs, as few as possible.
  4. Copy the token. It is shown once. Only a hash is stored, so losing it means making another.

You can revoke a token on the same screen. The list shows what each token may do, when it was last used and when it expires.

What a token is

  • A token carries its creator's authority, and never more. It is not a service account. A token made by someone who may not write in a private team writes nothing there, whatever scopes it has. When their membership is revoked, every token they made stops working with it.
  • A token is personal. Things done with it appear as done by its owner.
  • Scopes narrow, they never widen. A request has to pass the scope check and the same policies the web app uses.

One key per API

The suite has three APIs and they do not share keys:

API Credential Made in
Backlog Personal API token with scopes Backlog → Settings → API tokens
Docs Integration secret (capabilities, and the pages shared with it) Docs → Settings → Workspace → Connections (details)
Chat Personal token, optionally with the contracts scope Chat → Settings → API tokens (details)

Apps that act for other people

If you build an app that other people connect to their own workspace, do not ask them to paste a token. Backlog runs OAuth 2.0 with PKCE, and nothing to register in advance: the app registers itself against the installation it was pointed at.

GET  /.well-known/oauth-authorization-server   discovery (RFC 8414): where everything is
POST /oauth/register                           dynamic client registration (RFC 7591), public, PKCE-only
GET  /oauth/authorize                          the consent screen
POST /oauth/token                              exchange a code, and refresh

The person picks the workspace and the scopes on the consent screen. Access tokens last an hour and refresh tokens thirty days, so a client has to refresh; one that does not looks fine for an hour after every sign-in.

An OAuth token is narrower than a personal one: it is confined to the workspace that was granted, and a request for any other workspace answers 403, even one the person belongs to. GET /api/v1/me reports the grant in workspace (null for a personal token). Revoking an app under Settings → Connected apps removes the grant, and its tokens can no longer reach any workspace. The MCP server uses the same flow.

Errors you may meet here

Status Meaning
401 The token is missing, wrong, revoked or expired.
403 The token is valid but lacks the scope, or its owner may not do this.

More in Rate limits and errors.