---
title: "Members and invitations"
description: "Who can do what, and how a person joins an organization: only by invitation."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.invox.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Members and invitations

Memberships live on the LIVE organization and govern its test twin: manage them with the live id.

| Role | Scopes |
| --- | --- |
| `owner` | `organization:read`, `organization:write`, `members:read`, `members:write`, `service_accounts:read`, `service_accounts:write`, `issuers:read`, `issuers:write`, `series:read`, `series:write`, `invoices:read`, `invoices:emit`, `invoices:void`, `invoices:correct`, `customers:read`, `events:read`, `webhooks:read`, `webhooks:write`, `production:request`, `templates:read`, `templates:write`, `templates:promote` |
| `admin` | `organization:read`, `organization:write`, `members:read`, `members:write`, `service_accounts:read`, `service_accounts:write`, `issuers:read`, `issuers:write`, `series:read`, `series:write`, `invoices:read`, `invoices:emit`, `invoices:void`, `invoices:correct`, `customers:read`, `events:read`, `webhooks:read`, `webhooks:write`, `production:request`, `templates:read`, `templates:write`, `templates:promote` |
| `operator` | `organization:read`, `templates:read`, `issuers:read`, `series:read`, `invoices:read`, `invoices:emit`, `invoices:correct`, `customers:read`, `events:read` |
| `viewer` | `organization:read`, `issuers:read`, `series:read`, `invoices:read`, `customers:read`, `templates:read` |

## A person joins by invitation

1. An owner or admin calls `POST /v1/invitations` (permission `members:write`; `Idempotency-Key` required) with the `email` and the `role`. The service writes to that address with a code. The code is never returned by the API; `delivery` says whether the email went out.

2. The invited person signs in (see [getting a credential](/start/)) and calls `POST /v1/invitations/accept` (a person's access token) with that code as `token`. The email of their account must be VERIFIED and equal to the invited one. The answer carries the id of the organization to send in `X-Organization`. To show the person what they are accepting first, `POST /v1/invitations/inspect` answers the organization, the role and when it expires, and accepts nothing. A person without an agent uses the button of the email instead: it opens the web, which does the same two calls.

An invitation lasts 7 days. `GET /v1/invitations` lists them; `POST /v1/invitations/{id}/resend` sends a new code (the previous one stops working); `DELETE /v1/invitations/{id}` revokes it.

Accepting can refuse with: [`invitation_not_found`](/errors/#invitation_not_found), [`invitation_expired`](/errors/#invitation_expired), [`email_not_verified`](/errors/#email_not_verified), [`invitation_email_mismatch`](/errors/#invitation_email_mismatch). Inviting can refuse with: [`live_organization_required`](/errors/#live_organization_required), [`scope_not_grantable`](/errors/#scope_not_grantable), [`already_member`](/errors/#already_member).

## Changing and removing

`PUT /v1/members/{user_id}` (permission `members:write`) changes the role of someone who is already a member; `DELETE /v1/members/{user_id}` (permission `members:write`) removes them. Only an owner grants or removes the owner role, and an organization always keeps one ([`last_owner`](/errors/#last_owner)). The service accounts and keys a person created keep working: they belong to the organization.

Source: https://docs.invox.page/people/index.mdx
