Most common needs
Popular tasks
These are the problems people usually need to solve before they are ready for the deeper endpoint or workflow docs.
Create and verify a token
Generate a workspace token, test it with GET /api/external, and confirm the workspace and capability map before you script anything else.
Understand why a token only sees one workspace
Aurora tokens are intentionally workspace-scoped. They do not cross workspace boundaries and they do not log into the browser app.
Queue work for an automation agent
Assign issues to the token-backed automation identity or mention the agent in an issue comment, then let your worker poll assignedToMe.
Troubleshoot auth and lookup failures
Use the error code, not just the message text, to decide whether you need new credentials, new discovery data, or different keys.
FAQ
Common questions
Short answers to the questions that come up most often during setup and first integration work.
Why can my token see only one workspace?
Because Aurora tokens are scoped to exactly one workspace. That keeps reads, writes, queue identities, and automation behavior predictable. If you need multiple workspaces, create a token per workspace.
Why does my token fail on /settings or /board?
Those are browser app routes, not external API routes. API tokens work only on /api/external/* and the remote MCP connector surface.
How do automation agents show up in assignee lists?
Aurora derives automation queue identities from active API token names and returns them from GET /api/external/users alongside human workspace members.
What should I cache in my client?
Cache GET /api/external, /teams, /users, and /statuses per token workspace. Refresh them when workspace structure or token naming changes, not before every single write.
Troubleshooting
Where to look first when things fail
These checks tend to isolate the problem quickly without having to inspect the whole system.
401 Unauthorized
The request is missing a valid token or is calling a route outside the external API surface. Re-check the Authorization header and retry against /api/external.
404 or not found errors for known objects
The token may belong to a different workspace, or the client may be using stale ids or keys. Re-run discovery and confirm the workspace from GET /api/external.
Ambiguous or invalid project/status references
Supply teamKey when using projectKey, and reload statuses for the target team before a status update. Agents should branch on PROJECT_KEY_AMBIGUOUS and STATUS_INVALID_FOR_PROJECT.
Best first diagnostic
GET /api/external. It tells you whether the token is valid, which workspace it belongs to, and which capability flags are available in that workspace. Most auth and scope confusion becomes obvious from that single response.