Roles and permissions

Wexa ships four roles. You can tune three of them, add roles of your own, and assign several administration scopes to one person. This page says what each role can and cannot do, and then explains the second set of role names you will meet at the API, which is a genuine source of confusion.

The four roles

Settings → Roles (/settings/roles) lists them. Every person in an organization should hold exactly one.

Role	What it is for	Configurable?
Org Admin	Full administrative access across the organization	No
Department Admin	Department-scoped operator and administrator — complete access to their department's projects and data	Yes
Project Admin	Project-scoped operator and administrator — complete access to their project's data	Yes
Member	Basic agent operator — Simple mode only; runs agents and process flows rather than authoring them	Yes

Org Admin is deliberately not configurable. It is the tier that must always be able to fix anything, including a misconfiguration of another role, so there is nothing to edit and nothing to delete.

What each reaches

Access is expressed as a set of capabilities, and the most visible of those are the ten application areas. This table is the shipped default for each role.

Area	Org Admin	Department Admin	Project Admin	Member
Workspace	Yes	Yes	Yes	Yes
Connect	Yes	Yes	Yes	Yes
Context Graph	Yes	Yes	Yes	Read-only
Orchestrate	Yes	Yes	Yes	No
Actions	Yes	Yes	Yes	No
Simulate	Yes	Yes	Yes	No
Data	Yes	Yes	Yes	No
Insights	Yes	Yes	Yes	No
Governance	Yes	Yes	No	No
Settings	Yes	No	No	No
Manage roles	Yes	No	No	No
Curate the context graph	Yes	Yes	Yes	No
Build intelligence	Yes	Yes	No	No
Billing	Owner tier only	No	No	No

Two entries deserve a sentence each.

A member's Context Graph access is read-only and scoped. They see the viewer, not the curation tools, and what appears inside the viewer is filtered on the server against the data they are cleared for — not filtered in the browser. Exposing the area to them is safe for that reason.

A member cannot author, only run. They can read a process flow, run it, simulate it, test it and watch the run; they cannot write one or reconfigure an agent. Their ability to retrieve and ingest data is granted to their agent through its credential's scope, not through the application.

Who may create a department or a project

Administering something and creating one are different permissions, and the server enforces both.

	Org Admin (and owner)	Department Admin	Project Admin	Member
Create a department	Yes	No	No	No
Create a project	Yes	Yes — in a department they administer	No	No

A department administrator has complete authority inside their department: every project under it, existing or created later, plus its people and its scopes. What they cannot do is add to the organization's structure — creating a department is an organization-level act, and creating a project outside the department they administer would put it beyond their own scope. A project administrator administers the project they were given and does not spawn new ones. Both refusals are 403 from identity, not merely a hidden button.

Administering several departments or projects

Department and project administration are lists, not single values. One person can administer three departments and two projects, set independently of the plain project memberships they hold. See members and invitations for the screens.

This is also why a scoped role is refused without its scope: dept_admin with no department has nothing to administer, and nothing can be granted to them.

The owner tier

There is a fifth role in the data, and you will never see it offered. The organization's owner is stored as a distinct tier that is functionally identical to Org Admin — same capabilities, same access — and exists only so that an organization always retains one administrator who cannot be demoted. It folds into Org Admin everywhere it is displayed and everywhere it is counted, so nobody has to think about it.

Two older roles

Two roles predate this model and remain valid for accounts that already hold them, but are no longer offered when you assign a role: a governance-centric one, and a full-navigation one without analytics or billing. If you inherit an organization where somebody holds one, it still works; new people should be given one of the four above.

Changing what a role can do

Tuning a role that ships. PUT /settings/roles/builtin/{key} stores a per-organization override of that role's capabilities and scopes. The name and the key are fixed by the tier; only what it reaches is yours to set. Org Admin is never overridable.

Adding a role. POST /settings/roles with a name, an optional description, a capability list and a scope set. Constraints:

The name may not collide with a role that ships.
A duplicate name is refused with 409 "A role with that name already exists."
A custom role can be deleted; one that ships cannot. Deleting a role that people hold is refused with 409 "N users are assigned this role — reassign them before deleting."

Who may do any of this. Organization administrators only. Every role-management endpoint checks it and refuses everyone else with 403 "Only a super admin or org admin can manage roles." The Roles screen is gated by the same capability, so a department administrator never sees it.

Scopes on a role

Alongside capabilities, a role carries a scope set — which modules, connectors, models, entity types and actions its holders may use, plus a clearance for sensitive data classes. These are the same dimensions a department carries, and they compose the same way: restrict-only, bounded by the level above. A role's scopes narrow what its holders reach; they never widen it past what the department and project already allow. See departments and projects.

The other role names, at the API

The gateway's own constants are OWNER, ORG_ADMIN, ORG_MEMBER, PROJECT_ADMIN and PROJECT_MEMBER — uppercase, and rejected in any other spelling. Where an endpoint says it requires an administrator, it means one of OWNER, ORG_ADMIN or PROJECT_ADMIN; everything else is not an administrator for that purpose.

That distinction decides two things you will meet immediately:

Whether a credential can be issued at all. POST /v1/apikeys refuses a non-administrator with 403 "API key creation requires an admin role on this project".
What a credential can do by default. A key minted by an administrator that requests no explicit permissions gets the administrator's default set, which covers the whole tool surface. Any other role — and any role the gateway does not recognise — falls closed to reading the context graph and reading the documentation, and nothing else. Requesting permissions explicitly always wins, so a deliberately narrow key stays narrow. See credential management.

Deciding an approval over the REST API uses the same definition of administrator, and only within their own scope. In the console, who may decide depends on the approval and on the requester. See approvals.