Member types
Roles
Guests only see projects they are assigned to.
In Settings > Members, owner and admin users can see joined human account emails under display names. The member-list API only hydrates account emails when an owner/admin caller requests
includeEmail=1; pending or legacy invite rows may still expose the invitation email used to reserve the seat.
Scoped agent permissions
An agent has one stable identity. Humans edit its Projects, Product KPI creation, individual KPI permissions, Product-wide KPI permissions, and automation access without replacing its member ID, API keys, or OAuth profiles. Human roles remain unchanged. Agentrole is a compatibility projection; it is not the grant source.
Read GET /api/auth/me → auth.permissions for explicit grants, permission
revision, owner project following, and effective project access with sources.
Use atoll agent-context --live-permissions for the selected CLI profile, or
atoll_get_auth_context in full/public MCP. CLI context reports conflicts, tenant
mismatch or unavailable reads without switching identities or printing errors.
Project access remains project_members View/Edit/Admin. Optional owner following
uses the human owner’s current project access only. It never inherits the owner’s
organization strategy or administration permissions. Project access does not grant
Product KPI access. New scoped agents have no KPI-create permission by default.
kpi.create targets one Product or Organization. An agent must send product_id
explicitly: a Product UUID or null for Organization. KPI creation, its explicit
creator kpi.manage grant, and an optional initial snapshot commit atomically.
The response KPI includes effective_access: { level: "manage", source: "explicit_kpi_grant" }. Creating a KPI grants no access to existing KPIs. Removing
the creator’s grant removes access unless another explicit grant covers the KPI.
Names remain unique within their Product or Organization owner; duplicate creation
returns 409. An archived Product or incompatible Goal cannot receive the KPI.
KPI Read permits reading the measurement. Record includes Read and recording
non-formula snapshots. Manage includes Read, Record, definition/target changes,
and deletion. Ownership changes still require strategy ownership permission.
Product-wide grants cover current and future KPIs under that Product. Organization
scope covers organization-owned KPIs only; all_kpis explicitly covers every KPI
in the organization, including all Products. Grants add access; removing a narrow
grant cannot override a broader grant. KPI filtering happens before pagination and
counts. Selected formula measurements stay canonical; source issues and initiative
links require separate access.
Human-only GET and PUT /api/orgs/{id}/agents/{agentId}/permissions inspect and
replace permissions. PUT requires expected_revision, follow_owner_projects,
projects: [{ project_id, access_level }], and grants: [{ capability, target_kind, target_id }]. A stale revision or active execution conflict returns 409 without
a partial update. Stop active executions and reload before changing access. Grants
and project membership changes are audited together. Agents cannot administer
grants. Legacy agent role PATCH is rejected with agent_permissions_required;
legacy project PATCH remains a compatibility adapter. No CLI/MCP permission-write
tool is exposed because this control requires a verified human session.
Project webhook creation uses webhook.create(project). Creation atomically grants
its agent creator webhook.manage(new webhook) and webhook.dispatch(new webhook).
Manage and Dispatch are independently revocable. Sending also requires project
rule management and current project access. Project Admin alone grants agents no
webhook rights. Organization administration retains its explicit organization grant.
Delete agent uses terminal revoke. It permanently invalidates credentials and
execution authority, releases the agent slot, hides it from active agent lists and
pickers, and disables active automation rules that execute as that identity. Past
work, attribution, grant history and the member row remain. It cannot be undone.
Disable remains reversible and keeps the slot; enabling requires fresh credentials.
DELETE /api/orgs/{id}/agents/{agentId} remains the human-only idempotent adapter.
The stored marker stays lifecycle_state: "revoked". Use Show deleted agents
for history. Admin agent list APIs accept include_deleted=true for deliberate
history reads.
Teams
Teams group members for access and ownership. Use them for stable groups like Engineering, Design, Marketing, or a client team.Project access levels
When you add a member to a project, the selector groups humans, agents, and integrations so you can grant access to the right actor type. New project members default to
edit access in the app and API unless you choose or send a different accessLevel.
In Project Settings > Project Members, Role / scope identifies the member’s organization role or agent scope. Project access is the separate View, Edit, or Admin level for that project. A Project-scoped agent has the internal organization role guest and can still have Project access: Admin. This does not grant organization administration. Human guests keep the Guest label. Personal agents are labeled Personal agent and inherit their owner’s current project access.
Agents can belong to more than one project. Use project membership to give an agent only the workspaces it needs, then choose an appropriate default project in that agent’s CLI profile or install snippet for scheduled runs.
Personal agents are guest agents owned by one human member. They do not store a separate project access snapshot. Instead, their project access follows the owner dynamically, so adding or removing the human from a project changes what the personal agent can access.
Owners and admins can manage every agent. Human members can manage guest agents they created and their own personal agent. Agent-authenticated callers cannot manage other agents.
Workforce inventory
The Agents page uses the server-authorized workforce projection. Owners/admins default to organization context; individual owners default to their own agents. Use Workforce context to select a project where you have admin access. Project view/edit permission is insufficient. The selected project bounds rows, counts, projects, assignments, activity and navigation. It does not expose organization capacity or integrations. Use the search field to match visible agent names, visible project names, scope labels, or a visible personal-agent owner. Project filters use only projects already visible to the caller and group projects that share a name. Search and filters apply together, and the result count shows how many manageable agents match. Sort by name, latest authenticated use, or creation date. Latest authenticated use is a credential-use timestamp from an active API key or non-revoked OAuth profile; it is not an execution or health state. Agents without an authenticated-use timestamp appear last in that sort. A project-scoped guest can show no visible project access when the caller cannot see any of its projects. Select Detail on an authorized agent to review its safe identity, owner or creator, stable scope, caller-visible projects, latest authenticated use, open assignments, and recent readable issue Activity. Detail uses the same selected workforce context as the inventory. Read access does not imply management access. It does not reveal hidden project facts, and it does not present assignments or authenticated use as execution state. Heartbeat, profile, key, access and lifecycle actions each use their specific server capability. Key prefixes are absent without key management rights. Access editing in project context links to the complete own/org inventory. Owners and admins can reconcile the shared agent allowance at the top of Agents. The total shows used slots and the finite limit, or Unlimited. The breakdown counts all normal agents and API-key integrations, regardless of search filters. If the counts differ from the billing total, Inventory changed; refresh to reconcile requires a fresh read. Refresh inventory reloads the inventory and capacity together. Agents use one list. Project and search filters remain available. The default lifecycle view hides deleted agents. Select Show deleted agents for history. Delete permanently revokes access and releases capacity; Disable can be reversed with fresh credentials and retains capacity. API-key integrations remain separate.Common admin workflows
List members:Agent heartbeat management permissions
Organization administrators can grant Manage own heartbeat (heartbeat.manage_self) independently from Manage other agents’ heartbeats (heartbeat.manage_others). The self grant uses the Organization target with a null ID. The other-agent grant targets a same-organization agent UUID (target_kind: agent) or Organization for all other agents. Other never includes self. No agent receives these grants by default.
Both grants cover briefing policy and outbound configuration, including creating an outbound configuration. They do not grant project access, permission editing, agent lifecycle control or webhook creation/administration. Current followed-owner project access still applies. A project destination also requires the caller’s existing webhook.dispatch grant on that webhook and project access for both caller and target. Organization destinations require webhook.organization_manage.
Settings and previews contain only the caller/target resource intersection. Hidden saved selections return a generic unavailable flag. A delegated full replacement or reset conflicts if it would discard a selection the caller cannot inspect. Self reset can clear stale selections. Missing policy means the organization default, then the built-in default. PUT replaces the full policy/configuration; omitted fields are not explicit null. Preview sends nothing and records no acknowledgement. Test queues a labeled empty payload, returns queued rather than accepted, and uses the actual tester’s current authority.
Disabled/revoked callers cannot authenticate. Inactive targets cannot be changed or tested. A grant is not a project or destination permission. Atoll rechecks authority before writes, queueing and each retry. Losing the saved author’s authority stops pending delivery; adding a grant later does not revive an old wake. Requests already authorized and in flight cannot be recalled. Integration/setup keys cannot use these grants. Human management rules and the ordinary heartbeat read/ack contract are unchanged.
Use GET /api/orgs/{id}/heartbeat-targets?limit=25&offset=0 for bounded authorized target discovery. Per-agent management uses /api/orgs/{id}/agents/{agentId}/heartbeat-policy (GET/PUT/DELETE), /heartbeat-preview (POST), /outbound-heartbeat (GET/PUT/DELETE), and outbound /preview or /test (POST). Responses and errors are private/no-store. Missing, foreign and unauthorized targets are concealed as 404; unsupported actor classes use 403, invalid input 400 and authorized lifecycle/scope conflicts 409. Reconcile a lost write/test response before retrying.
Typed CLI source commands are heartbeat targets, heartbeat policy get|set|reset|preview and heartbeat outbound get|set|disable|preview|test, with --agent self or an exact UUID. Set reads the complete JSON from --body-file PATH or stdin (-). Policy preview accepts an optional draft file. Outbound preview uses saved settings. No URL or secret input is accepted by these commands. Bare heartbeat and its cursors/acknowledgement stay unchanged.
Full/private MCP has typed list/get/set/reset/preview/test tools. Existing full/public atoll_get_auth_context reports the new grants truthfully. New public heartbeat management tools remain unavailable during the public tool freeze. CLI, MCP and skill package availability depends on a separate package release; source changes do not prove that an installed version contains these commands.
