# User invitations

> Invite users by email with scoped permissions or a role preset, including invite-only registration.

## Invite before creating an account

Admins invite an email address from the invitation screen, choosing an assignable permission
snapshot or [role preset](/docs/roles). The account is created only when the recipient accepts the
single-use link and chooses a password. The actor can include only permissions they hold.

Set `Auth:RegistrationEnabled=false` for invite-only onboarding. External-provider sign-in honors
the same setting, so enabling Google or GitHub does not reopen public sign-up. Configure a bootstrap
administrator through `Admin:AdminEmails` so someone can send the first invitation.

## Manage pending invitations

Admins can list, resend, revoke and update permissions on pending invitations. Resending replaces
the token; accepted and revoked invitations cannot be revived. A lapsed invitation can be renewed.
Expiry, resend cooldowns, send limits and retention are configured under `Invitations`.

Only the token hash is stored. The email link carries the token in a URL fragment; the SPA removes
it from browser history and submits it in a request body. Invitation records participate in the
user's data export and account erasure, and lifecycle changes are audited.

The repository references are `docs/api/user-invitations.md` and `docs/frontend/user-invitations.md`.

## Verify

- Invite an address, open its email in Mailpit and accept the link.
- Confirm the new account receives the chosen grants and the link cannot be reused.
- Disable public registration and confirm an unknown external-provider account cannot register.