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.