> Source: https://wexa.ai/docs/administration/roles-and-permissions # 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](/docs/administration/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](/docs/administration/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](/docs/administration/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](/docs/administration/approval-workflows#who-may-approve).