Permission Sets

Permission Sets give organization admins fine-grained, scoped control over what members can do with agents — who can view, edit, delete, publish, and create them, and how widely that access reaches. You compose a named bundle of scoped permissions and assign it to users.

Think of a permission set as a reusable access profile. You might create an “Agent Editors” set that lets members view every agent in the organization but only edit the agents on their own team, and a separate “Agent Admins” set that grants full control. Members inherit the combined access of every set assigned to them, always resolving to the union of scopes they hold.

How It Works

Every permission set is scoped to a single organization and defines access to a resource through a combination of actions and scopes.

Concept	What it means
Resource	The kind of object the permission applies to. Currently agents.
Action	What the member is allowed to do: view, edit, delete, publish, or create.
Scope	How far the action reaches — from a user’s owned resources all the way to the whole organization.
Principal	Who the set is assigned to. Currently users.

Scope grants are written at the organization level rather than per-member, so assigning or updating a permission set propagates to every affected member in constant time.

Scopes

Each of the view, edit, delete, and publish actions is assigned a scope..

Scope	Grants the action on…
all	Every agent in the organization (broadest).
project	Agents belonging to projects the member can access.
team	Agents user’s team(s) can access.
own	Only agents the member owns (narrowest).

The Permissions Object

A permission set's access is expressed as a JSON permissions object. The agents resource takes four scoped actions and one boolean create flag:

Action	Type	Description
view	scope \| null	View / read access to agents in scope.
edit	scope \| null	Modify an agent's configuration.
delete	scope \| null	Delete agents in scope.
publish	scope \| null	Publish staging changes live to production.
create	boolean	Whether the member may create new agents.

Example

{ "agents": { "view": "all", "edit": "team", "delete": null, "publish": "own", "create": true } }

View auto-escalation: A member who can edit, delete, or publish an agent must also be able to see it. If any of those actions is granted a broader scope than view, view is automatically raised to match. If the broader scopes mix team and project (neither of which implies the other), view escalates all the way to all.

Creating & Managing Permission Sets

Organization admins can create, update, and delete permission sets. Set names must be unique within an organization.

A few sets are treated specially:

System sets (is_system) are built-in presets. They cannot be deleted, and only their default flag may be changed — name, description, and permissions are locked.

Default sets (is_default) are auto-assigned to newly invited/added organization members. An organization must always keep at least one default set, so you cannot remove or delete the last one.

Endpoints

Method	Endpoint	Description
GET	/api/v2/permission-sets	List the organization's permission sets. Supports search (query), sorting (sort_by=name), and optional pagination.
POST	/api/v2/permission-sets	Create a permission set from a name, optional description, default flag, and permissions object.
GET	/api/v2/permission-sets/{permission_set_id}	Retrieve a single permission set by ID.
PUT	/api/v2/permission-sets/{permission_set_id}	Update name, description, default flag, or permission scopes.
DELETE	/api/v2/permission-sets/{permission_set_id}	Delete a permission set and revoke its permission grants. System sets cannot be deleted.

Assigning Members

A permission set takes effect once it is assigned to a user. You can approach assignment from either direction — add many users to one set, or add many sets to one user.

Partial success: Batch assignment requests are processed item by item. Valid items succeed even if others fail; each failure is returned with a reason (for example, principal not found in the organization, or the per-principal cap reached). Items already assigned are treated as successful (idempotent).

Cap: Each user can hold at most 20 permission sets within an organization.

Endpoints

Method	Endpoint	Description
GET	/api/v2/permission-sets/{permission_set_id}/members	List the users assigned to a set. Supports search, sorting (name, subject_type), and pagination.
POST	/api/v2/permission-sets/{permission_set_id}/members	Assign one or more users to the set.
DELETE	/api/v2/permission-sets/{permission_set_id}/members	Remove one or more users from the set.
POST	/api/v2/users/{user_id}/permission-sets	Assign a single user to multiple permission sets in one call.

Effective Permissions

A member usually holds several permission sets. Their effective permission for each action is the union of scopes granted by all of those sets. The create flag is effective if any assigned set grants it.

For example, if one set grants edit at team scope and another grants edit at all, the member can edit any agent in the organization.

Directly Shared Agents

Permission sets grant scoped access across whole populations of agents, but an agent can also be shared directly with an individual user (or with every user in the organization, by making the agent Public). A direct share does not grant actions by itself. It names which agent a user may act on; the actions they can perform still come entirely from the permission sets they hold.

A direct share is granted at one of two levels:

Share level	What it can unlock (given a matching permission set)
member	View only.
admin	View, edit, delete, and publish.

Resolution

For each action, a directly-shared user's access is the intersection of their share level with their capability for that action. A capability is the scope-agnostic union of every scope grant the user holds for that action across all of their assigned permission sets — in other words, "does this user have view (or edit, delete, publish) at any scope?"

Member share: the user can view the agent if they hold any permission set that grants view at any scope. A member share contributes nothing to edit, delete, or publish.

Admin share: the user can view, edit, delete, or publish the agent — action by action — if they hold any permission set that grants that same action at any scope. An admin share never unlocks an action the user has no permission set for.

Public Agents: Public agents are shared with all users in the organization at once with member access. Every user then resolves against their own view capability individually, so only members who already hold view somewhere gain access.

Note: Direct shares to a team behave slightly differently — a team share is gated at team scope rather than by the scope-agnostic capability. The capability-based resolution above applies to shares made directly to an individual user.

How It Works#

Scopes#

The Permissions Object#

Creating & Managing Permission Sets#

Endpoints#

Assigning Members#

Endpoints#

Effective Permissions#

Directly Shared Agents#

Resolution#

How It Works

Scopes

The Permissions Object

Creating & Managing Permission Sets

Endpoints

Assigning Members

Endpoints

Effective Permissions

Directly Shared Agents

Resolution