> Source: https://wexa.ai/docs/administration/members-and-invitations

# Members and invitations

People join an organization by being invited into it and then signing up against that invitation.
Inviting is the only way the Users screen offers to bring someone in, and nobody can join an
organization they were not invited to. This page covers the administrator's side and then the
invitee's.

## Inviting someone

Settings → Users (`/settings/users`) → **Invite users**. The form collects a name, an email address,
a role, and — depending on the role — a department or a project. It posts to
`POST /settings/users/invite`.

Four checks run before an invitation is created, and each has a distinct failure:

1. **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 would
   reject their address.
2. **The role must exist.** `400 Unknown role "…"`. Both the roles that ship and any custom role
   your organization has created are accepted.
3. **A scoped role must carry its scope.** `dept_admin` with no department, or `project_admin` with
   no project, produces someone whose role says administrator while nothing can actually be granted
   to them. It is refused at the door rather than created and left broken. The scope is also checked
   to belong to your organization, so an identifier pasted from elsewhere does not work.
4. **You cannot invite above your own authority.** A department or project administrator cannot
   invite an organization administrator.

Inviting the same address twice does not create a second invitation: the pending one is updated in
place with the new name, role and scope, and its date is reset.

### After you send it

The invitation appears in the Users list straight away as a row with status **Invited**, alongside
real accounts.

- **Resend** — `POST /settings/invites/resend` re-sends the same invitation and resets its date.
- **Copy link** — the invitation link is returned to the screen, so if mail delivery fails you can
  send it yourself. A delivery failure is reported rather than swallowed: the invitation record is
  kept either way, and the screen tells you it did not send.

## What the invitee experiences

The invitation email carries a link of the form `/signup?accessKey=…&email=…`. Following it:

1. **The signup page greets them by name and names what they are joining.** Before rendering, it
   calls `GET /users/invite-preview?accessKey=…&email=…`, which returns the name the administrator
   entered and the organization and role they were invited to. An invitation that has been revoked,
   or a mismatched key-and-email pair, returns `404 "This invitation is not valid or has been
   revoked."` — and says nothing about which half was wrong.
2. **They fill in the ordinary signup form**, with the invite key already filled in from the link.
   They never see or handle the raw key.
3. **Signing up joins your organization rather than creating one.** The key must be bound to your
   organization *and* their email must be on its allow-list; the key alone is refused with
   `"This access key is registered to an org which this email hasn't been invited to"`.
4. **Their role and scope come from the invitation, not from a default.** Without that they would
   land as a plain member whatever the invitation said. The pending invitation is marked accepted,
   and the access the role implies is materialized at the same moment — an invited organization
   administrator who was not provisioned this way would arrive able to see no projects at all.
5. **They are signed in immediately.** Email verification is deliberately skipped; the account is
   created already active. They land on the first-run screens described in
   [getting started](/docs/administration/getting-started).

## Managing someone who is already in

All of these are on the Users screen, and each has its own endpoint because they are genuinely
different things.

| 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` | Several at once — this is a list, not a single value |
| Which projects they administer | `PUT /settings/users/{id}/project-admin` | Several at once |
| Which projects they simply belong to | `PUT /settings/users/{id}/project-memberships` | Independent of whether they administer anything |
| Suspend them | `POST /settings/users/{id}/suspend` | |

Administering someone and belonging to a project are deliberately separate lists. A person can be a
member of six projects and administer one of them, and neither fact is inferred from the other.

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

### Three rules that apply to every one of these

- **You cannot administer yourself.** Not your own role, not your own suspension. The screen hides
  the controls on your own row and the server refuses it regardless.
- **You cannot grant a role above your own.** The role you are setting is capped at your own
  authority, the same ceiling that applies to invitations.
- **You see only the people you can administer.** A department administrator's Users list is filtered
  to their department's people; a project administrator's to their project's. You always see your
  own row. Organization administrators see the organization, and only they see pending invitations.

### The last owner

Every organization must keep at least one owner who cannot be demoted. The role change that would
remove the last one is refused. This is why the owner tier is not offered as a role you can assign —
see [roles and permissions](/docs/administration/roles-and-permissions) for how it is presented.