# Backlog Server Tokens

> A server token lets a machine read and write the backlog of one project on its own, for example a script on an always-on Linux server that files cards.

- Area: Desktop, mobile and web
- Plans: All plans
- Last checked against the product: 2026-11-05
- Web page: https://agentsroom.dev/docs/backlog-server-tokens

## What it does

A server token lets a machine read and write the backlog of one project on its own, for example a script on an always-on Linux server that files cards. It does not expire after 24 hours like a desktop login, it needs no desktop switched on, and you revoke it by itself without signing anything else out. It covers that one project and nothing else on your account.

## Where to find it

**Settings > Backlog**, section **Server tokens**, for the project currently open. Also in the project settings, **Backlog** tab. Searching "Server tokens" in Settings lands on it.

## How to use it

1. Open the project, then **Settings > Backlog > Server tokens**.
2. Type a name that says which machine it is for, such as `CI server`, then click **Create token**. Cards it files carry this name.
3. Copy the token right away. It is shown once and cannot be read back: the server only keeps a fingerprint of it.
4. Put it on the machine, then use it one of two ways.

**With curl or any HTTP client**, which needs nothing installed:

```
curl -X POST https://agentsroom.dev/api/backlog \
  -H "Authorization: Bearer arb_..." \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<project id>","title":"Disk almost full","description":"Details"}'
```

The screen gives you this command filled in. It is written for a Linux or macOS shell. In Windows PowerShell, use `Invoke-RestMethod` with the same URL, header and body.

**With the AgentsRoom MCP tools**, for a script or an agent CLI that already speaks MCP. Start `app-mcp-server.cjs` from the `resources` folder of an AgentsRoom install (`/opt/AgentsRoom/resources/` with the Linux package) with these variables, and nothing else is needed: no settings file, no desktop, no copied login.

```
AR_BACKLOG_TOKEN=arb_...
AR_PROJECT_ID=<project id>
AR_API_BASE_URL=https://agentsroom.dev
```

To cancel a token, click **Revoke** on its row. The machine loses access on its next request. Nothing else changes: your own sessions and your other tokens keep working.

**What a token can do:**

- List and read the cards of the project, on your own board and on its team board if your account sits on it.
- File a card: title, description, status, type, tags, parent, epic.
- Edit a card, append to its description, move it to a column, close it.
- Read and write internal comments, checklists and links between cards.

The HTTP routes are `GET` and `POST /api/backlog`, `PATCH /api/backlog/:id`, `GET` and `POST /api/backlog/:id/comments`, `/api/backlog/:id/checklist`, `GET` and `POST /api/backlog/relations`, `DELETE /api/backlog/relations/:id`, and `GET /api/backlog/columns` and `/api/backlog/hierarchy`. Every other route of the API answers 401 to a token.

## Settings

None. Tokens are managed from the section above. They are created by a person signed in to the app: no agent tool creates or lists them.

## Agent tools (MCP)

With `AR_BACKLOG_TOKEN` set, the MCP server lists these tools and no others: `backlog_list`, `backlog_get`, `backlog_create`, `backlog_update`, `backlog_internal_comment`, `backlog_internal_comments`, `backlog_link`, `backlog_unlink`, `backlog_checklist`. `backlog_get` has no `effectiveExecutor` block in this mode, since a token cannot see your agents.

## Providers

All providers, no difference. A token does not run an agent.

## Mobile

Not on the mobile app: tokens are created and revoked on the desktop.

## Limits

It is a credential sitting on a machine that is always on, so it is built to do little harm if it leaks. It cannot:

- **Start an agent**: moving a card to **In progress** is refused, as are a programmed start, an executor (agent, team, provider, model), a worktree and a reviewer. Closing a card with a token does not fire an **On ship** trigger.
- **Reach anyone else**: it cannot publish a card, edit a public ticket or set a reporter's e-mail, and it never sees a reporter's e-mail address.
- **Destroy**: it cannot delete a ticket, reorder the board, or change columns and their prompts.
- **Touch the rest of your account**: projects, memory, prompts, settings, other backlogs, or another token.

A request that asks for one of these is refused as a whole with a message saying which field, and nothing is written. A card it files can still be picked up later by your own automation, like any other card: AI classification, **Start next**, a lane you set up.

The numbers:

- 10 live tokens per project.
- 120 cards per hour per token, so a script stuck in a loop cannot bury a board. Past that, the API answers 429 with `Retry-After`.
- Not available in Local mode: that backlog stays on your computer, out of reach of a server.
- A board you have open shows cards filed by a token at its next refresh, not instantly.
- The token acts with your account's access: if you leave a team, it loses that team's board like you do.

## Common questions

- **My script loses backlog access every 24 hours.** It is using a copy of the desktop login from `settings.json`, which is short-lived and renewed only by the desktop. Replace it with a server token.
- **Does a token expire?** No. It works until you revoke it. It also stops when you reset your password, when your account is banned or deleted.
- **Does signing out of the app stop my server?** No. Signing out of a computer leaves tokens alone. Resetting your password revokes them all, because a password reset is what you do when you think someone else got in.
- **I lost a token. Can I see it again?** No, the server does not keep it. Revoke it and create a new one.
- **How do I know a token is still in use?** Its row shows when it was last used, to within a few minutes.
- **Can one token cover two projects?** No. Create one per project.
- **The MCP server says the token was revoked and stops calling the API.** Create a new token and restart the server with it. It does not retry a revoked token in a loop.
- **Do I need this if AgentsRoom itself runs on the server?** No. With `agentsroom --server` the app keeps its own login alive and its agents already have every tool. A token is for a script or a CLI running without the app.
- **Can an agent create a token for itself?** No. Only someone signed in to the app can, from Settings.

## Related

- [Backlog Task Board](https://agentsroom.dev/docs/backlog-task-board.md): the board these cards land on.
- [Linux Server Mode](https://agentsroom.dev/docs/linux-server-mode.md): the whole app on a server, when you want agents there and not only cards.
- [Webhook Triggers](https://agentsroom.dev/docs/webhook-triggers.md): the other direction, an outside service starting an agent.
- [Local status API](https://agentsroom.dev/docs/local-status-api.md): another way for a local script to read AgentsRoom, on the same computer.
