Backlog Server Tokens
- Desktop, mobile and web
- All plans
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
- Open the project, then Settings > Backlog > Server tokens.
- Type a name that says which machine it is for, such as
CI server, then click Create token. Cards it files carry this name. - Copy the token right away. It is shown once and cannot be read back: the server only keeps a fingerprint of it.
- 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 --serverthe 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: the board these cards land on.
- Linux Server Mode: the whole app on a server, when you want agents there and not only cards.
- Webhook Triggers: the other direction, an outside service starting an agent.
- Local status API: another way for a local script to read AgentsRoom, on the same computer.