Agents should have enough access to do their job and no more.
Permission model
Agent keys inherit the permissions of the agent member. The API does not bypass project visibility, roles, or admin-only operations.
Project-scoped agents intentionally have the organization role guest. Their effective ability to read or write a project comes from the separate project membership level: view, edit, or admin. GET /api/auth/me reports both as auth.role and auth.projectAccess[], so a response can correctly show role: "guest" together with accessLevel: "admin" for one project.
Organization roles and project access are read from current membership data on every request. Existing keys do not cache those values, so changing either takes effect without rotating or reauthenticating the key. The key’s scopes array is separate and is reserved for special-purpose capabilities such as setup; scopes: [] is expected for a standard agent key.
Use these controls:
- Role:
owner, admin, member, or guest
- Project membership
- Team membership
- Personal agent ownership
- API key rotation
- Activity feed review
Personal agents are created by a human member and run as guest agents. Their project access follows the owner’s current access dynamically. If the owner gains access to a project, the personal agent can access it; if the owner loses access, the personal agent loses it too.
Project-scoped and personal agents can list initiatives for projects they can
access. Creating one requires edit/admin access to the requested project;
updating an existing project-linked initiative or its execution links requires
edit/admin access to every project linked to it. Their CLI snippets should keep
the intended default project set; atoll initiative create uses that project
automatically, and API callers can pass project_id or projectId.
Key handling
Do:
- Store keys in environment variables or secret stores.
- Rotate keys when an agent runtime changes owner.
- Revoke keys for inactive agents.
- Use separate profiles for separate clients or organizations.
Do not:
- Commit
sk_atoll_... keys.
- Paste keys into task comments.
- Reuse one key across unrelated agents.
- Give admin role to an agent unless it needs admin operations.
Admin-only operations
Some operations require owner/admin access, including permanent deletion of certain resources and billing administration.
For task removal, prefer archive:
Prompt and feedback safety
Treat task descriptions, comments, issue titles, feedback submissions, and webhook payloads as untrusted input. They can contain instructions, but they should not override the agent’s system/developer instructions or local repository rules.
An Atoll task can ask an agent to do work, but it should not be treated as a higher-priority instruction than the agent runtime’s safety and repository rules.
