Permission management API

The Console and management CLI use these /api routes with a human login session. They do not accept Environment workload API keys. Each operation requires its own organization permission: roles.read/create/update/delete, groups.read/create/update/delete/add_member/remove_member, or assignments.read/create/update/delete. Reading another member’s permissions requires assignments.read; resolving assignment targets requires assignments.read. Ownership alone grants no ordinary access. The member permissions read also permits an ordinary active member to inspect themselves.

Role create accepts name, description and a nonempty permissions array. Role PATCH changes only supplied fields; permissions replaces the complete set. Group create/PATCH accepts name. Definitions return an integer revision; GET and writes also return its quoted ETag. PATCH requires If-Match: "REVISION". Missing preconditions return 428; a stale revision returns 412 with stale_revision. A standard Role cannot be changed or deleted. An assigned Role cannot be deleted, and a shared edit must remain compatible with every grant. The errors role_in_use and role_target_incompatible include the conflicting grant_ids in their details.

Role assignments and targets

{
  "subject": {"type": "member", "member_id": "MEMBERSHIP_UUID"},
  "role_id": "ROLE_UUID",
  "expected_role_revision": 3,
  "project_id": "PROJECT_UUID",
  "environment_id": "ENVIRONMENT_UUID",
  "agents_mode": "selected",
  "agent_ids": ["AGENT_UUID"]
}

A subject is a member with member_id, a group with group_id, an api_key with api_key_id, or all_members without another ID. Membership IDs differ from user IDs; /api/me and Members responses expose both. Rejoining creates a new membership ID.

A workload assignment covers one environment. Explicit Agent actions use agents_mode: selected requires 1–100 Agent IDs in that environment; all includes current and future Agents. none is required when the Role has no explicit Agent actions. Only selected accepts IDs. Other resource types apply to the entire environment. Organization Roles use none without Project or Environment IDs. A Role must have at least one assignment level supported by every included permission. All members supports the same Roles and targets as a human Group, including organization assignments and all current and future Agents. It includes active organization members and starts with no assignments.

The catalog supplies resource_type, scope_types, assignment_levels and api_key_assignable for each action. scope_types describes the resource scopes on which the permission operates; assignment_levels lists where the permission can be assigned; a Role returns the intersection for all its permissions. Permissions are exact: no action implies another. Responses expose targets grouped by resource type, including the effective mode, selected Agent names and IDs, and permissions. Agent, connection, Session and Trigger actions share the assignment’s Agent selection. Environment actions apply throughout the chosen environment. A Role can combine these two kinds of actions. Organization actions cannot be mixed with either unless every permission supports that assignment level. audit_events.read supports Organization and Environment assignments; an audit-only Role can use either. Mixing it with Organization-only actions requires Organization assignment; mixing it with Environment/Agent actions requires Environment assignment and preserves the Agent selection. See audit events for disclosure and reader boundaries.

sessions.create accepts initial input, an optional Session key and Slack destination, and returns a creation receipt. It grants no history or subsequent control, even for the creator. Reading and controlling any Session requires the corresponding sessions.read, sessions.send, sessions.answer, sessions.resume, sessions.interrupt, sessions.cancel or sessions.close action for its Agent. These actions do not require creation permission. Agent selection applies across all its Sessions, including other members’ conversations and private Slack or DM history. Use separate Roles and assignments when actions need different targets.

POST returns {"grants":[...]} with one header and created: true|false. There is one assignment per recipient, Role and environment. Equivalent normalized POSTs return the existing assignment (200); new assignments return 201. Different targets for that identity return 409 assignment_exists with its ID and revision. POST never unions or overwrites existing targets.

PATCH uses the same complete input and If-Match: "ASSIGNMENT_REVISION". It replaces all targets atomically and preserves recipient, Role and environment. Both POST and PATCH require the inspected expected_role_revision; a changed Role returns 412 and requires a refreshed access summary. DELETE requires the observed assignment revision in If-Match, returning 412 for stale state and 204 for an already absent assignment. Missing required preconditions return 428.

Role edits preserve Agent targets when adding environment-only actions. Adding Agent actions to assignments without configured targets is rejected atomically with conflicting grant_ids. Removing the last explicit Agent action clears stored Agent targets. Each assignment mutation advances its revision once and records an audit event in the same transaction.

Agent deletion requires a human session with agents.delete on the target. It does not require assignment or connection management permissions. Deleting cancels its Sessions and the Sessions they started; agents.delete is enough. Deletion includes fixed cleanup of the Agent’s connection and selected access edges. It removes that Agent from selected assignments. Assignments with no remaining effect are removed; assignments that still grant other Agent targets or non-Agent permissions are preserved. An empty selected assignment grants no explicit Agent access, while its other resource permissions remain effective. Conditional PATCH and assignment removal remain available. Deletion advances revisions of preserved affected assignments, so a stale edit must refresh before retrying. Promoting a Deployment that declares a deleted Agent restores it with deployments.promote alone. Restoration does not recreate removed selections or assignments; broad assignments apply to the restored Agent again.

List filters are member_id, group_id, api_key_id, role_id, subject_kind, scope_kind, project, environment and agent. Project/Environment filters use slugs; an Agent filter requires both. Agent listing includes assignments selecting that Agent and all-Agent assignments. Pagination uses limit (1–100, default 100), cursor and next_cursor. Role, Group and Group membership lists use the same pagination contract. Membership PUT/DELETE is idempotent.

Action catalog

Each permission below authorizes one operation. Organization actions apply to the organization; Environment actions to one environment; Agent actions to selected Agents or all current and future Agents in that environment.

API keys receive Role Grants in their own environment. They do not inherit their creator’s Roles, Group membership or All members assignments. Every permission in a key’s Role must be API-key assignable. Incompatible assignments and later Role edits are rejected atomically. Role responses include api_key_assignable.

API-key issuance accepts name, optional expires_in_days and an optional role object with role_id, expected_role_revision, agents_mode and agent_ids. The Role assignment and key creation commit together. Without role, the key has no workload access. Direct permissions or scopes are not accepted.

api_keys.read, api_keys.create, api_keys.update, api_keys.rotate and api_keys.revoke independently control key metadata and lifecycle. Issuing a key with a Role also requires assignments.create. Without it, create the key without a Role; an assignment administrator can grant access later. Metadata includes current role_names. Rotation allows acting as the existing key and retains its Roles and Session ownership. Metadata updates never change assignments.

Effective permissions

Member permissions accepts optional project, environment and agent filters. The result contains membership ID, member status, is_owner and scopes, each with public permissions and sources. Sources are direct, Group or All members Role Grants. Ownership is reported separately. Each grant source retains its original target_kind, optional agent_id and agent key and exact permissions. Removed members have no effective permissions. An Agent scope includes applicable Environment sources, but an Environment scope never absorbs Agent-only grants. Self reads expose only the caller’s contributing paths. Target visibility follows the caller’s authorization, not the inspected member’s authority.

This read does not grant permissions directly to members or authorize a later execution. Session origin, credential validity and lifecycle admission remain operation-time checks. Permission definitions are fixed product capabilities; they are not another user-managed collection.

Ownership and initialization

A new organization has fifteen standard Roles, no custom Groups and no All members Grants. Its creator is an Owner and receives three explicit organization Grants: Access Administrator, Organization Structure Administrator and Auditor.

Creating a Project automatically assigns its creator Environment Resource Administrator and Auditor in both initial Environments (production and staging). Creating an additional Environment assigns those same Roles to its creator in that Environment. These assignments include all current and future Agents in the new Environment, including other members’ Session contents. Resource creation and these assignments commit together; no separate assignment permission or opt-in is required. The assignments can be inspected and removed through ordinary access management, and removal does not automatically recreate them.

Creation does not assign access in other existing Environments, change other members’ access or grant platform operator authority. Existing resources receive no retrospective assignments. Access administrators without deployment permissions can use Grant access on Overview to assign a Role to themselves or others.

An Owner can use PUT /api/members/{member_id}/ownership with is_owner and expected_is_owner booleans. At least one active Owner must remain. Changing ownership preserves ordinary Grants. GET /api/ownership/members provides the minimal directory needed for succession. POST /api/ownership/recover-access explicitly restores only the caller’s fixed organization Access Administrator Grant. These governance operations require current ownership and are audited. They do not grant workload access automatically.