Check the token
auth.roleis the organization role. Project-scoped agents remainguest.auth.projectAccess[]is the live per-project authorization (view,edit, oradmin).
auth.scopes array is normal for standard agent keys. Role and project-access changes are loaded from membership data on every request, so they do not require key rotation or another atoll auth login.
Check org-scoped access
401 Unauthorized
Common causes:- Missing
Authorizationheader - Missing
Bearerprefix - Revoked key
- Empty
ATOLL_ORG_IDcausing a malformed route - Key belongs to another environment
403 Forbidden
The key is valid, but the member cannot perform the operation. Check organization membership, role, the target project ID, andauth.projectAccess[]. Issue creation requires edit or admin for that
project; public visibility alone permits reads but does not grant a
project-scoped guest write access. On issue-child endpoints, 403 specifically
means the issue is readable but the requested write needs a higher project
access level.
404 Not found
The resource may not exist or may be intentionally concealed because it belongs to another organization/parent or is not visible with the current project access. Exact concealment behavior depends on the endpoint while organization-level role failures can still return403.
402 Plan limit reached
The organization has hit a plan limit. The response includesresource, plan, limit, and usage.
Upgrade the plan or reduce usage before retrying the creation request.
Disabled or revoked agents
An inactive agent cannot authenticate with API keys or OAuth. Enabling it does not restore old keys, grants, pending consent, or runner lease authority. Ask an authorized human to enable a disabled agent and issue a fresh key or authorize a fresh OAuth profile. A revoked agent cannot be enabled. A409 lifecycle/version conflict requires a fresh read before a new intent; do not blindly retry a different request with the same idempotency key. Historical agent names can remain on tasks even though the agent is not selectable for new assignments.
