Permission Sets

Permission Sets give organization admins fine-grained, scoped control over what members can do with the resources — agents, corpora, and workflows — 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 a “Content Editors” set that lets members view every agent in the organization, edit the agents on their own team, and edit only the corpora they own, and a separate “Admins” set that grants full control over all three resources. 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: agents, corpora, or workflows.
Action	What the member is allowed to do: view, edit, delete, publish, or create. Not every resource supports every action — see Resources and their actions below.
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.

Resources and their actions

The three governed resources do not all take the same actions or the same scopes. The differences follow the shape of each resource in the product rather than an arbitrary choice:

Resource	Scoped actions	Available scopes	Boolean	Why it differs
agents	view, edit, delete, publish	all, project, team, own	create	Agents live inside projects and have a staging → production publish step.
corpora	view, edit, delete	all, team, own	create	A corpus belongs to the organization, not to a project, so there is no project scope. Corpora are never published.
workflows	view, edit, delete	all, project, team, own	create	Workflows live inside projects like agents, but are never published, so there is no publish action.

Sending an action or a scope a resource does not support (for example workflows.publish, or corpora.view: "project") is rejected by the APIs rather than silently ignored.

Scopes

Each scoped action is assigned a scope.

Scope	Grants the action on…
all	Every resource of that kind in the organization (broadest).
project	Resources belonging to projects the member can access. Agents and workflows only.
team	Resources the user’s team(s) can access.
own	Only the resources the member owns (narrowest). A corpus or workflow is owned by its creator.

The Permissions Object

A permission set's access is expressed as a JSON permissions object with one block per resource. Each block takes that resource's scoped actions plus a boolean create flag.

agents — four scoped actions and one boolean:

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.

corpora — three scoped actions and one boolean:

Action	Type	Description
view	scope \| null	View the corpus, its documents, sitemaps, conversation starters, and connected agents.
edit	scope \| null	Edit corpus metadata, upload/delete documents, manage sitemaps, trigger re-indexing — and manage the permissions panel.
delete	scope \| null	Delete corpora in scope.
create	boolean	Whether the member may create new corpora.

workflows — three scoped actions and one boolean:

Action	Type	Description
view	scope \| null	View and run workflows in scope.
edit	scope \| null	Modify a workflow's nodes, edges, and configuration — and its shares.
delete	scope \| null	Delete workflows in scope.
create	boolean	Whether the member may create new workflows.

Example

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

A resource block may be omitted entirely. An absent block is not a decision about that resource — it is how every set authored before corpora and workflows were onboarded looks, and editing a set only to adjust agents must not silently change a member's corpus access. To explicitly withhold access, include the block with every action null and create: false.

No separate manage action: for corpora and workflows, managing shares — granting, updating, and revoking user or team access — is part of edit. A member who can edit the resource can also manage who else can reach it.

View auto-escalation: A member who can edit, delete, or publish a resource 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 — per resource, independently. If the broader scopes mix team and project (neither of which implies the other), view escalates all the way to all. Corpora have no project scope, so they can never hit that case.

Roles vs. Permission Sets

Ejento AI controls access through two complementary layers. Understanding the difference is key to setting people up correctly.

Account roles — a broad tier assigned to each person that sets their baseline reach across the organization.

Permission Sets — fine-grained, reusable rules layered on top of a role that decide exactly what a person can create, view, edit, delete, and deploy for which specific agents, corpora, and workflows.

A useful way to think about it: roles decide how far someone's authority extends; Permission Sets decide exactly what they can touch within each resource.

The account roles

Role	Scope of control	What they can typically do
Global Admin	The entire organization	Full control: manage all users, teams, projects, agents, corpora, and workflows; configure organization settings; create and assign Permission Sets. This is the highest level of access.
Application Admin	Application-level functions and resources	Elevated administrative access over many areas and shared resources, but without full organization-admin authority. Sits below a Global Admin.
User	Only the resources they own or are granted	Works within their own agents, projects, corpora, and workflows, plus anything explicitly shared with them.

Note: On any individual resource (a specific agent, corpus, workflow, team, or project), a user can additionally hold an Admin or Member access, which further refines what they can do with that one item — independent of their org-wide role.

How Permission Sets fit on top

Roles set the ceiling; Permission Sets carve out the precise access beneath it. Assigning someone the "User" role doesn't, by itself, say what they can do to which agents, corpora, or workflows — the Permission Sets you attach to them do.

High-impact actions stay gated. Even a user who can edit a configuration may be blocked from deploying it to a live environment.

In short: use roles to establish broad trust levels (who is an admin vs. a regular user), and use Permission Sets to precisely define what each user can see and change within agents, corpora, and workflows.

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 resource and action is the union of scopes granted by all of those sets. The create flag is effective if any assigned set grants it.

Each resource is aggregated independently — a set that grants broad agent access says nothing about corpora or workflows.

For example, if one set grants agents.edit at team scope and another grants agents.edit at all, the member can edit any agent in the organization; if neither set grants corpora.edit, they can still edit no corpus.

Directly Shared Resources

Permission sets grant scoped access across whole populations of resources, but an individual agent, corpus, or workflow can also be shared directly with a user or a team. A direct share does not grant actions by itself. It names which resource 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 — plus publish for agents

Corpus roles: `viewer` and `editor` are retired

Corpus sharing used to offer three roles — viewer, editor, admin. It now uses the same two tiers as agents and workflows:

Old relation	New relation	Why
`viewer`	`member`	Renamed — read-only access
`editor`	`admin`	Merged. An editor could only edit, while `admin` could edit, delete and re-share a corpus; `admin` alone is the tier that now carries those.

What this means for API clients

VALID_RELATIONS for a corpus grant is now ["admin", "member"].

Note: A former editor now sits in the admin tier, so they also resolve against the corpus delete capability. They can delete the corpus only if a permission set grants them corpora.delete.

How access resolves

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) on this resource at any scope?"

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

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

Public Agents and Corpora: these 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. Workflows cannot be made public.

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.

System and default Permission Sets

Not every Permission Set behaves the same way. Two special categories carry rules you can't override, and there are a few organization-wide limits worth knowing before you start creating sets.

System Permission Sets

System Permission Sets cannot be modified. Their scopes are fixed. You can, however:

Set/Unset them as default (on/off), and

Assign or remove users.
You just can't change what the set grants.

Default Permission Sets

A default Permission Set is one that is automatically assigned to every new user added to the organization, so people start with a baseline of access from day one. Because of this, defaults follow special rules:

An organization must always have at least one default Permission Set.

The last remaining default cannot have its default field toggled off — this guarantees the organization is never left without a default. (Once another set is marked default, the previous one can be freely toggled again.)

Turning a set's default on or off changes only future assignments to new users; it doesn't retroactively add or remove the set from existing users.

Assignment limits

A user can have at most 20 Permission Sets assigned at any one time. Plan for this ceiling when designing sets — favor a smaller number of well-scoped sets over many narrow ones.

Quick reference
Rule Detail
System sets Scopes are locked; only the default toggle and user assignments can change.
Minimum defaults At least one default must always exist in the organization.
Last default Its default field cannot be toggled off while it's the only default.
New users All default sets are auto-assigned to every new user.
Per-user limit Maximum of 20 Permission Sets per user at a time.

Rule	Detail
System sets	Scopes are locked; only the default toggle and user assignments can change.
Minimum defaults	At least one default must always exist in the organization.
Last default	Its default field cannot be toggled off while it's the only default.
New users	All default sets are auto-assigned to every new user.
Per-user limit	Maximum of 20 Permission Sets per user at a time.

How It Works#

Resources and their actions#

Scopes#

The Permissions Object#

Roles vs. Permission Sets#

The account roles#

How Permission Sets fit on top#

Creating & Managing Permission Sets#

Endpoints#

Assigning Members#

Endpoints#

Effective Permissions#

Directly Shared Resources#

Corpus roles: viewer and editor are retired#

How access resolves#

System and default Permission Sets#

System Permission Sets#

Default Permission Sets#

Assignment limits#

How It Works

Resources and their actions

Scopes

The Permissions Object

Roles vs. Permission Sets

The account roles

How Permission Sets fit on top

Creating & Managing Permission Sets

Endpoints

Assigning Members

Endpoints

Effective Permissions

Directly Shared Resources

Corpus roles: `viewer` and `editor` are retired

How access resolves

System and default Permission Sets

System Permission Sets

Default Permission Sets

Assignment limits