> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Backlog

> Connect Backlog by Nulab to CloudThinker for issue tracking, milestone planning, wiki, and pull-request context

Connect your Backlog space to enable CloudThinker agents to track issues, plan milestones, read wikis, and pull ticket context during code review. Backlog authenticates with a **space-scoped API key** that inherits the issuing user's project access.

***

## Prerequisites

* A **Backlog space** with access to the projects you want to work in.
* A **space-scoped API key**, created from the issuing user's **Personal Settings → API** tab.
* For create/update actions: the key's user needs the matching **project permission**.

<Info>
  Read-only tracking works with any key whose user can see the target projects. Creating or updating issues, wikis, and pull requests additionally requires that user to have write permission on the project. If your space restricts API access, a space administrator must enable it before keys can be issued.
</Info>

***

## Setup

<Steps>
  <Step title="Create an API key">
    In Backlog, open your profile menu and go to **Personal Settings → API**. Enter a memo (e.g. `cloudthinker`) and click **Submit** to generate the key, then copy it.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Navigate to **Connections → Backlog** and enter:

    * **Domain**: your full Backlog domain, e.g. `<myorg>.backlog.com` — the full host, not just the space key
    * **API Key**: the key you just created

    Click **Connect**. CloudThinker verifies the credentials and shows a **Connected** status.
  </Step>
</Steps>

<Warning>
  Copy the API key when you create it and store it securely. Treat it like a password — anyone with the key has the issuing user's access to the space.
</Warning>

***

## Connection details

| Field                 | Description                                                | Example               |
| --------------------- | ---------------------------------------------------------- | --------------------- |
| **BACKLOG\_DOMAIN**   | Full Backlog domain for your space, not just the space key | `<myorg>.backlog.com` |
| **BACKLOG\_API\_KEY** | Space-scoped API key used to authenticate the connection   | —                     |

***

## Required permissions

The API key inherits the access of the user who issued it. Read operations work with any key whose user can see the target projects. Create, update, and delete operations additionally require the user to have **write permission** on the project **and** explicit [approval](/guide/approval) in CloudThinker.

<Tip>
  Follow least privilege: issue the key under a user with only the project access CloudThinker needs, and keep write actions approval-gated rather than removing the guardrail.
</Tip>

***

## Agent capabilities

Once connected, agents have read access to your Backlog projects, issues, wikis, and repositories, plus a set of approval-gated write operations.

| Capability                    | Description                                                                                                                      |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Project & space discovery** | List projects, categories, custom fields, priorities, and recent space activity                                                  |
| **Issue tracking**            | Search, read, and count issues; create and update issues, change status, and add comments — **writes require approval**          |
| **Milestones & releases**     | List milestones/versions and plan releases; create or update them — **writes require approval**                                  |
| **Wiki & documents**          | Read project wikis and documents; create or update wiki pages — **writes require approval**                                      |
| **Git & pull requests**       | Inspect repositories and pull requests, pull ticket context during code review, and comment on PRs — **writes require approval** |

### Verify the connection

```text theme={null}
@alex list my Backlog projects and show the open issues in one of them
```

### Example prompts

```text theme={null}
@alex summarize the open Backlog issues for the PLATFORM project and #report anything overdue
@alex this PR references PROJ-123 — pull the Backlog ticket and #recommend whether the change matches it
@alex list the milestones for my main project and their completion status
```

<Note>
  For spaces with many projects, scope requests to a single project or milestone so the agent returns focused results.
</Note>

***

## Troubleshooting

<Accordion title="401 Unauthorized">
  The API key is missing, expired, or revoked — or API access is not enabled for the space. Issue a fresh key under **Personal Settings → API**, confirm the space allows API access, and reconnect.
</Accordion>

<Accordion title="Requests return 404 or the wrong space">
  **BACKLOG\_DOMAIN** is set to just the space key instead of the full domain. Use the complete host, e.g. `<myorg>.backlog.com`, and reconnect.
</Accordion>

<Accordion title="Connection works but no projects or issues appear">
  The key's user is not a member of any project, or lacks visibility on the ones you expect. Add the user to the target project in Backlog, then re-run discovery.
</Accordion>

<Accordion title="Create or update actions fail with a permission error">
  The key's user lacks write permission on the project. Re-issue the key under a user with the right project role, and approve the action when prompted.
</Accordion>

<Accordion title="Results look cut off on large projects">
  Very large responses are trimmed to keep replies focused. Scope the request to a single project, milestone, or status, or ask for a count first and then drill in.
</Accordion>

***

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Least-privilege user** — issue the API key under a user with only the project access CloudThinker needs.
- **Correct domain** — store the full domain (`<myorg>.backlog.com`), not just the space key.

***

## Related

<CardGroup cols={2}>
  <Card title="Atlassian Connection" icon="https://mintcdn.com/cloudthinker/aLd-ttc-SCW-aFky/images/icons/atlassian.svg?fit=max&auto=format&n=aLd-ttc-SCW-aFky&q=85&s=64fcf0381646a233832602a9086a14eb" href="/guide/connections/atlassian" width="24" height="24" data-path="images/icons/atlassian.svg">
    Jira and Confluence issue tracking and knowledge base
  </Card>

  <Card title="Approval" icon="shield-check" href="/guide/approval">
    How approval-gated actions work
  </Card>
</CardGroup>