Skip to main content

Backlog

Read, create and update Backlog issues, comments, wikis and pull requests from agent work.

Connect it with: Sign in (OAuth), API key. Backlog's own documentation: https://developer.nulab.com/docs/backlog/auth/.

What agents can do​

Connect Backlog so the agents working your tasks can reach it. With it connected, they can:

  • Start a task from a Backlog issue: assign it to your Jaah user, mention that user in a comment or add the jaah category (Settings > Integrations > Issue trackers > Add tracker).
  • Read the Backlog issue a Jaah task names: its description, status, assignee, milestones and comments.
  • Create follow-up issues in the right project when an agent finds more work.
  • Comment on an issue with progress, a summary or a pull request link, and change its status when the work lands.
  • Read and update wiki pages, and list a project's open issues to plan or report on work.
  • Read Backlog Git repositories' pull requests and comment on them.

Before you start​

  • A Backlog account that is a member of the projects agents should reach.
  • Your space URL: the address you open Backlog at, on backlog.com, backlog.jp or backlogtool.com.
  • To connect with a sign-in: nothing else - approve Jaah on Backlog's consent screen.
  • To connect with an API key: permission to create one in Personal settings > API (a space admin can turn API keys off for the space).
  • A Jaah account. Anyone can add a personal secret; an organization secret needs an Org Owner or Admin.

Connect with Backlog​

This is the quickest way in: you sign in to Backlog and approve what Jaah asks for. You never copy a key.

  1. In Jaah, open Secrets and select New.
  2. Search for Backlog and select its card.
  3. Give the secret a name you will recognize, such as the account or workspace it reaches, and choose who can use it (see Who can use it).
  4. Enter your Space URL (see Connect with an API key for where to find it): Backlog's sign-in page is on it.
  5. Select Connect Backlog. Backlog's sign-in window opens.
  6. Sign in to Backlog if asked, check the access listed, and approve it.
  7. You land back in Jaah on the new secret, which reads Connected once its test passes.

If the button reads Jaah app not configured, this Jaah has no app registered at Backlog yet. Use an API key, or your own OAuth app, until it does.

Scopes Jaah requests​

Jaah asks Backlog for these scopes, and no others. A scope marked optional is a checkbox on the Connect screen: untick it and agents simply cannot do that part.

Jaah names no scopes on the sign-in request: the vendor grants the access set on Jaah's app itself, and lists it on its approval screen.

Connect with an API key​

Prefer this when you cannot sign in with Backlog — for example a service account, or a token your admin issued. On the Connect screen select Use an API key instead.

Find each value first:

Then add it to Jaah:

  1. In Jaah, open Secrets, select New, and pick the Backlog card.
  2. Name the secret and choose who can use it.
  3. Select Use an API key instead.
  4. Fill in Space URL, API key.
  5. Select Save. Jaah tests the secret straight away (see Test the connection).

Jaah encrypts what you type and never shows it again — not to you, and not to an admin.

Use your own OAuth app​

Register your own OAuth app at Backlog when your company requires apps it controls, or before this Jaah has an app registered there.

  1. Create an OAuth app in Backlog's developer console, https://backlog.com/developer/applications/signin (Backlog's documentation).
  2. Set its redirect URI to https://app.jaah.ai/api/credentials/connect/callback (on your own Jaah, its console address followed by /api/credentials/connect/callback).
  3. Give it the scopes in Scopes Jaah requests.
  4. Copy its client ID and client secret.
  5. In Jaah, start a new Backlog secret, select Use your own OAuth app, paste both values and select Connect Backlog.

The client secret is stored with the connection, encrypted, like any other secret value.

Test the connection​

Select Test on the secret. Jaah calls Backlog's API once (GET <Space URL>/api/v2/users/myself) with the stored values, and shows who it answered as, or which value Backlog refused and the status it answered. Jaah also tests automatically when you save or reconnect.

The last result and its time stay on the secret's page, so you can see whether it still works without testing again.

Who can use it​

Every secret has an owner, and the owner decides who can use it:

  • Personal — only your own tasks can use it. This is the default.
  • Organization — every task in the organization can use it. Only Org Owners and Admins can choose this.
  • Attached to a project — every task on that project can use it, whoever started the task. See Attach a secret to a project.

More on owners and access: How secrets work.

Use it in an agent session​

An agent asks for the secret with its credential_get tool, by the secret's path, when it needs it, and gets the values for that one call. The path is the owner's prefix and the secret's name:

  • org/<name> for an organization secret,
  • projects/<project>/<name> for one attached to a project,
  • me/<name> for your personal one.

A signed-in connection hands the agent a live access_token, with access_token_expires_at. Jaah refreshes it before it expires, so an agent never handles a refresh token.

A key connection hands the agent its fields: base_url, api_key.

Tell the agent in your task description which secret to use, for example “use the Backlog secret org/backlog”.

Manage, rotate or disconnect​

Everything is on the secret's page under Secrets:

  • Rotate a key: create a new key at the vendor first, then select Replace on the secret and paste it. Revoke the old key at Backlog once the test passes. Steps: Replace or delete a secret.
  • Reconnect: when Backlog ends the grant (a password change, a revoked app, an expired refresh), the secret shows Needs reconnect. Select Reconnect and sign in again; agents get the new token on their next call.
  • Disconnect: select Delete. The stored values are destroyed and agents lose access on their next call. To end access at Backlog's side too, revoke Jaah in Backlog's settings, or revoke or delete the key at Backlog.

Limitations​

  • Agents act as the account that connected: issues, comments and wiki edits they make are attributed to that person.
  • Backlog has no scopes: a sign-in or an API key grants everything that account can do in the space.
  • One connection reaches one space; add another connection for each extra space.
  • Backlog Enterprise installed on your own servers is not supported, only spaces Nulab hosts.
  • Backlog rate-limits API calls per user; very large bulk edits can be slowed or refused.
  • Agents can do only what the connected Backlog account and its granted scopes allow.

Troubleshooting​

Test says Backlog rejected the API key (401)

The key was deleted or mistyped, or belongs to another space. Create a new key in Personal settings > API and select Replace on the secret.

Test says the Space URL is refused

Enter only the space address, such as https://yourspace.backlog.com, with no path. Spaces on other domains cannot be connected.

Backlog shows an error about the redirect URI on the sign-in screen

You are using your own OAuth application and its Redirect URI is not the one on this page. Set it exactly and try again.

The secret shows Needs reconnect

The sign-in was revoked in Backlog or the account left the space. Select Reconnect and approve Jaah again.

Still stuck? Select Test and read the result: it names the value Backlog refused and the status it answered.

FAQ​

Can a Backlog issue start a Jaah task?

Yes. Add the space under Settings > Integrations > Issue trackers > Add tracker with the secret of a dedicated Backlog user named Jaah; assigning an issue to that user, mentioning it or adding the jaah category then starts a task, and Jaah posts its progress on the issue.

Which account do agents act as?

The Backlog account that approved the sign-in or created the API key. Use a dedicated Backlog member for agents if you want their work attributed separately.

Does the connection expire?

A sign-in renews itself: Jaah refreshes the one-hour access token automatically. An API key lasts until you delete it.

Can agents use Backlog's MCP server?

Not through Jaah yet: Nulab offers its MCP server only as software you run yourself, and Jaah links hosted MCP servers. Agents call Backlog's API with this connection instead.

Can Jaah or an admin see the key or token?

No. Jaah stores it encrypted and never shows it again. Only the tasks allowed to use the secret receive it, at the moment they ask for it.

Can I connect more than one Backlog account?

Yes. Add one secret per account, each with its own name, and tell the agent which one to use.