Members and roles

People join an organization by being invited, and the role they hold decides what they can reach. You need an administrator to invite anyone; only an organization administrator manages roles.

Open Settings, then Users (/settings/users), and choose Invite users.
Enter a name, email and role. A Department Admin needs a department and a Project Admin a project.
Send the invitation. The invitee follows the emailed link, signs up and gets the role from the invitation. If mail fails, use Resend or Copy link.
To change someone later, use their row on the Users screen: role, departments or projects they administer, projects they belong to, or suspend.
To tune or add a role, open Settings, then Roles (/settings/roles).

Limits

Limit	Behavior
Existing email	`409`: that email already belongs to a member.
Scoped role	`dept_admin` needs a department and `project_admin` a project, or the invitation is refused.
Your own authority	You cannot invite or grant a role above your own, or change your own role or suspension.
Last owner	Cannot be demoted.
Roles	Organization administrators only. A duplicate name is `409`; deleting a role people hold is `409`.

More details

Create the departments and projects first if the invitee needs one.

How it works

An administrator invites a name, an email, a role and, for a scoped role, a department or project.
The invitee follows the emailed link, which carries the key and their email, and signs up with the form filled in.
Signup joins your organization because the key is bound to it and the email is on its allow-list.
The invitation's role and scope apply from the first sign-in, and the access the role implies is created at that moment.

The four roles

Settings, then Roles (/settings/roles). Every person 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, with complete access to their department's projects and data	Yes
Project Admin	Project-scoped operator and administrator, with 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 misconfigured role, so there is nothing to edit or delete.

The shipped default reach of each role, over the application areas and the main capabilities:

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

A member's Context Graph access is read-only and scoped: they see the viewer, not the curation tools, and what appears is filtered on the server against the data they are cleared for, not in the browser, which is why exposing the area to them is safe.

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

Who may create	Org Admin (and owner)	Department Admin	Project Admin	Member
A department	Yes	No	No	No
A project	Yes	Yes, in a department they administer	No	No

A department administrator has complete authority inside their department, including projects created later, its people and its scopes, but cannot add to the organization's structure. Both refusals are 403 from identity, not only a hidden button.

Invite someone

Settings, then Users (/settings/users), then Invite users. The form posts to POST /settings/users/invite and collects a name, email, role and, depending on the role, a department or project. These checks run first:

The email must not already be in the organization. 409 "That email already belongs to a member of this organization." Inviting them again would send them to a signup page that rejects their address.
The role must exist. 400 Unknown role "…". Shipped and custom roles are both accepted.
A scoped role must carry its scope. dept_admin needs a department and project_admin a project, or the invitation is refused rather than created broken. The scope must belong to your organization.
You cannot invite above your own authority. A department or project administrator cannot invite an organization administrator.

Inviting an address twice updates the pending invitation in place with the new name, role and scope, and resets its date.

The invitation appears in the Users list as Invited. Resend (POST /settings/invites/resend) re-sends it and resets its date. Copy link gives you the link if mail delivery fails; a delivery failure is reported rather than swallowed, and the record is kept either way.

What the invitee sees

The link is /signup?accessKey=…&email=….

The signup page greets them by name and names the organization and role, from GET /users/invite-preview?accessKey=…&email=…. A revoked invitation or mismatched pair returns 404 "This invitation is not valid or has been revoked." without saying which half was wrong.
They fill in the ordinary form, never handling the raw key.
Signup joins your organization only if the key is bound to it and their email is on the allow-list; the key alone is refused with "This access key is registered to an org which this email hasn't been invited to".
Role and scope come from the invitation, not a default (without it they would land as a plain member), and the pending invitation is marked accepted. An invited organization administrator not provisioned this way would see no projects.
They are signed in immediately. Email verification is skipped and the account is created active. They land on the first-run screens in getting started.

Manage someone already in

All of these are on the Users screen.

Action	Endpoint	Notes
Change their role	`PUT /settings/users/{id}/role`	Optionally moves them to a department at the same time
Which departments they administer	`PUT /settings/users/{id}/dept-admin`	A list, set several at once
Which projects they administer	`PUT /settings/users/{id}/project-admin`	A list
Which projects they belong to	`PUT /settings/users/{id}/project-memberships`	Independent of administering
Suspend them	`POST /settings/users/{id}/suspend`

Administering and belonging are separate lists: a person can belong to six projects and administer one, and neither is inferred from the other. One person can administer three departments and two projects. A scoped role without its scope has nothing to administer.

The screen also maps the identities a person signs in with at connected systems to their Wexa account, and can mark an entry as a service account. Their data follows the mapping from the next query onwards.

You cannot administer yourself, neither your own role nor your own suspension. The controls are hidden on your row and the server refuses regardless.
You cannot grant a role above your own.
You see only the people you can administer. A department administrator sees their department's people and a project administrator their project's, plus your own row. Only organization administrators see the organization and pending invitations.

Tune or add a role

Only organization administrators may; every role endpoint otherwise answers 403 "Only a super admin or org admin can manage roles." and a department administrator never sees the Roles screen.

Tune a shipped role. PUT /settings/roles/builtin/{key} stores a per-organization override of its capabilities and scopes. Name and key are fixed; Org Admin is never overridable.
Add a role. POST /settings/roles with a name, optional description, capability list and scope set. The name may not collide with a shipped role, and a duplicate is 409 "A role with that name already exists."
Delete a role. Custom roles only. Deleting one people hold is 409 "N users are assigned this role — reassign them before deleting."

A role also carries a scope set (modules, connectors, models, entity types, actions and a sensitive-data clearance). It composes like a department's: restrict-only, bounded by the department and project, never wider. See departments and projects.

Limits and behavior

Topic	Behavior
Last owner	Every organization keeps at least one owner who cannot be demoted; the role change that would remove the last is refused.
Owner tier	A fifth role, functionally identical to Org Admin, never offered when assigning; it exists so an organization always keeps an administrator who cannot be demoted. It folds into Org Admin wherever displayed or counted.
Two older roles	A governance-centric one and a full-navigation one without analytics or billing. They still work for accounts that hold them but are not offered; give new people one of the four.

The role names at the API

The gateway's constants are OWNER, ORG_ADMIN, ORG_MEMBER, PROJECT_ADMIN and PROJECT_MEMBER, uppercase and rejected in any other spelling. Where an endpoint requires an administrator it means OWNER, ORG_ADMIN or PROJECT_ADMIN.

Issuing a credential. POST /v1/apikeys refuses a non-administrator with 403 "API key creation requires an admin role on this project".
Default permissions. An administrator's key requesting none gets the administrator default set, covering the whole tool surface. Any other role, and any role the gateway does not recognise, falls closed to reading the context graph and the documentation. Explicit permissions always win. See credential management.

Deciding an approval over REST uses the same definition, within the administrator's own scope. In the console, who may decide depends on the approval and the requester; see approvals.

Organizations, departments and projects: the structure these roles are scoped to.
Credential management: who should hold an API key and what it can do.
Approvals: who may decide a held call.