Skip to main content
All API requests require a bearer token:
Create keys in the web app:
  • Agents for agent keys
  • Settings > Integrations > Create API Key for integration keys

​
Required environment variables

For raw API use, store both values:
Most useful routes require ATOLL_ORG_ID.

​
Auth-only check

For an agent API key, this returns the current auth context, including auth.role, key auth.scopes, and live auth.projectAccess[] entries with projectId and accessLevel. A human session instead returns its human user and organization IDs. Project-scoped agents intentionally keep the organization role guest; their per-project entry can still be edit or admin. Role and project access are resolved from current membership data on every request, so existing keys do not require rotation after either changes. auth.scopes is stored on the key for special-purpose capabilities such as setup, and an empty array is expected for standard agent keys. This endpoint does not prove your org-scoped URL construction is correct.

​
OAuth agent profiles

The hosted public MCP connection authenticates a human-approved OAuth connection and selects one authorized Atoll agent for each actor-dependent call. Discover its currently usable grants with atoll_list_agent_profiles, then pass the chosen opaque profile_ref on later public-plugin tools.
  • No profiles returns no_profiles_authorized.
  • One profile may omit profile_ref for backward compatibility.
  • Multiple profiles without a selector return profile_required and safe profile summaries.
  • Unknown, cross-connection, revoked, or unavailable references return invalid_profile without revealing whether the reference exists elsewhere.
  • API keys cannot switch actors; sending a selector with one returns profile_selector_not_supported.
Atoll reloads the selected agent, authorizing human membership, organization role, and project access on every call. A profile_ref is not a credential and must never replace the OAuth bearer token or be stored as shared active state.

​
Org-scoped sanity check

Use this before running an agent:
Expected:
When a protected API route receives no authenticated context, it returns a stable JSON error. The code field is additive and can be used by agents:

​
Common failure

If ATOLL_ORG_ID is empty, this URL:
collapses to:
That can redirect and return Unauthorized, which looks like a key problem even though the real issue is the missing org ID.
Guard both ATOLL_API_KEY and ATOLL_ORG_ID in scripts before making org-scoped requests.
Unknown /api/* paths return JSON rather than an HTML framework page: