Skip to main content

Check the token

If this fails, the key is missing, malformed, revoked, or for a different environment. For an agent, inspect both fields:
  • auth.role is the organization role. Project-scoped agents remain guest.
  • auth.projectAccess[] is the live per-project authorization (view, edit, or admin).
An empty 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

Expected:

401 Unauthorized

Common causes:
  • Missing Authorization header
  • Missing Bearer prefix
  • Revoked key
  • Empty ATOLL_ORG_ID causing 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, and auth.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 return 403.

402 Plan limit reached

The organization has hit a plan limit. The response includes resource, 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. A 409 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.