# User registration (registration modes, invites, approval, email confirmation)

How users sign up and confirm their email address, the registration modes, invite codes, approval of requests, password resets, and sign-up blocks.

## From sign-up to the app

![The paths of a new user: the sign-up form or a login provider, the checks that can refuse the sign-up, the state that each registration mode gives, and the approval and email confirmation before the app. The list below says the same.](https://github.com/mycroblog/my/blob/main/docs/operations/images/sign-up-flow.svg?raw=true)

From the top of the diagram down:

- **Start.** A visitor creates an account on the sign-up page (`/auth/sign_up`) with a username, an email address and a
  password, which the page does not offer while [registration is limited to login providers](#registration-limited-to-login-providers).
  Or the visitor signs in with a [login provider](https://mycroblog.dev/next/operations/login-providers/) whose account is not linked to a user yet; when
  the provider allows sign-ups (`-allow-signup`), the visitor gets the same form without the password field.
- **Checks, in order.** The registration mode (`closed` refuses every sign-up), the limit per network (5 per 30 minutes),
  CAPTCHA (when `captcha` is not `none`), the [sign-up blocks](#sign-up-blocks) (`reject` refuses, `require_approval`
  holds for approval), the invite code (it must be usable, and `invite` mode requires one), the plugin of
  [`signup.check`](https://mycroblog.dev/next/operations/decision-hooks/#sign-ups) for a sign-up without an invite, and a username and email address that
  are not taken. A sign-up that fails a check is refused with an error on the form, and nothing is written.
- **State right after registering.** The new user is signed in at once. In `open` mode the registration is approved,
  or waits for approval with `mail = none`; in `approval` mode it waits for approval, or is approved with a usable invite;
  in `invite` mode it is approved. A `require_approval` block or a hold by `signup.check` leaves it waiting in any mode.
- **Until the account is ready.** A registration that waits needs a moderator's approval (`my registration approve`, or
  the admin screens). The email address must be confirmed through the link in a mail with `mail = smtp`; an address that
  the login provider verified is confirmed at once, and with `mail = none` no confirmation is needed. A rejected
  registration is not approved, and the account cannot use the app.
- **The app.** A ready account goes to the welcome step (a display name and an avatar), then to the home timeline.

The sections below describe each step.

## The sign-up page

Users register at `https://<host>/auth/sign_up` with a username, an email address and a password, unless [registration is limited to login providers](#registration-limited-to-login-providers).
After registering, that browser is signed in right away.
Like the sign-in page, it is protected by a CSRF token and by rejecting cross-origin requests.
When you choose CAPTCHA for bot protection, the sign-up and sign-in pages show its widget and need JavaScript ([CAPTCHA](https://mycroblog.dev/next/operations/captcha/)).

The registration mode is the instance setting `registration_mode`. Choose it with the CLI or in the web client on the "Registration" page of "Server settings" (`/admin/settings/registration`) ([instance settings](https://mycroblog.dev/next/operations/instance-settings/)). A change applies from the next registration.
While the server announces its closure and after it closes, registration is treated as `closed` whatever the setting says ([admin CLI](https://mycroblog.dev/next/operations/admin-cli/#announcing-the-end-of-the-service)).
So it is on a [one-person server](https://mycroblog.dev/next/operations/instance-settings/#one-person-server), where invites, the review of registrations, and the sign-up blocks are not offered either, and no way creates an account, `my admin create` included.

```sh
my instance set registration_mode invite
```

| Mode | Page | State right after registering |
| --- | --- | --- |
| `open` | Anyone can register; an invite code is optional | Approved, except with `mail = none`, where it waits for a moderator's approval (see below). An invite changes nothing but records who invited the user |
| `approval` (default) | Also asks "Why do you want to join?" (optional, up to 1,000 characters); an invite code is optional | Waiting for approval; approved at once with a usable invite |
| `invite` | An invite code is required | Approved |
| `closed` | Only says that registration is not accepted | None |

- In every mode but `closed`, the page has an invite code field, filled in from the link of an invite (`?invite=<code>`). A code that does not work (unknown, revoked, expired, used up, or of a member who can no longer invite) is refused in every mode, not ignored, so that a mistyped code does not go unnoticed.
- A sign-up block that requires approval keeps a registration waiting for approval even with an invite ([sign-up blocks](#sign-up-blocks)).
- With a plugin set for the decision hook [`signup.check`](https://mycroblog.dev/next/operations/decision-hooks/#sign-ups), a sign-up without an invite is also reviewed by that plugin after the CAPTCHA and the blocks, which can hold it for approval or refuse it.

- Registrations from the same network (IP address; `/64` for IPv6) are limited to 5 per 30 minutes. Beyond that the server returns `429` with `Retry-After`.
- If the username or the email address is taken, the page shows an error on that field and writes nothing (an invite is not consumed either).
- When you set up [external login providers](https://mycroblog.dev/next/operations/login-providers/) (OpenID Connect, GitHub, Discord or Mastodon) and let new users sign up with one, the sign-in and sign-up pages show a button for each enabled provider, labelled with the provider's display name exactly as you entered it (a GitHub provider shows "Sign in with GitHub", and a Discord one "Sign in with Discord", in the visitor's language).
  Someone whose account at the provider is not linked to a user of this server gets the same sign-up form without the password field, and the new user signs in with the provider only.
  The registration mode, the invite code, the reason, CAPTCHA, the sign-up blocks, `signup.check` and the network limit apply as on the password form; in `closed` mode, or when the provider does not allow sign-ups, the sign-in page says that no account is linked.
  An address that the provider marks as verified (`email_verified`; for GitHub, the primary address when it is verified; for Discord, the address when Discord marks it verified) is confirmed at once if the user keeps it; any other address, and every address of a user who signs up with a Mastodon server, which gives none, is confirmed by mail as below.
  An email address that matches an existing user never links that user: the form says the address is taken.
  A user with two-factor authentication still enters the code after signing in with a provider.
  A GitHub provider asks GitHub for the `user:email` scope, and also `read:org` when you list allowed Organizations; the server then checks on every sign-in that the user belongs to one of them and refuses the sign-in otherwise. Register `https://<host>/auth/external/<provider ID>/callback` as the callback URL of your GitHub OAuth app.
  A Discord provider asks Discord for the `identify` and `email` scopes, and also `guilds` when you list allowed servers; the server then checks on every sign-in that the user belongs to one of them. Register the same callback URL in your Discord application.
- A signed-in user links an account at a provider under "Linked accounts" in settings, after confirming with the password, a passkey, or another linked account, and only for providers that allow links.
  The browser must be signed in to the sign-in pages as the same user; otherwise the server asks to sign in first.
  An account at a provider that another user links is refused, and a user links at most one account per provider.
  A user can unlink an account unless it is the last way to sign in (no password, no passkey, and no other linked account).
- A user without a password and without passkeys confirms the operations that otherwise ask for them (setting a password, adding a passkey, deleting or moving the account, linking another account) by signing in again at a linked provider.
  An OpenID Connect provider is asked to authenticate the user again (`max_age=0` and `prompt=login`), and an earlier authentication is refused.
  The confirmation works once, for that operation only, within 10 minutes; signing in with an account that is not the linked one counts as a wrong attempt, against the same limit as a wrong password.
- On every registration and sign-in, the server records the client IP address (and, for sign-in, the User-Agent). The records are removed automatically after 180 days
  (the instance settings `session_origins_retention_days` and `registration_origins_retention_days`, at least 90 days). Records of an account under a retention hold are kept ([record retention and holds](https://mycroblog.dev/next/operations/moderation/#record-retention-and-holds)).
  State this retention period in your privacy policy ([privacy policy template](https://mycroblog.dev/next/operations/privacy-policy-template/)).

## When a user can use the app

Users who are waiting for approval, were rejected, or have not confirmed their email address can still sign in on the sign-in page. So can users who deactivated their own account, until the date of its deletion: they see that date there, and can reactivate or delete the account ([moderation](https://mycroblog.dev/next/operations/moderation/#accounts-that-their-owners-deactivated)).
After signing in, they see what they are waiting for (a moderator's approval, or confirmation of the email address), or that their registration was not approved, and they cannot go further.
Only approved users can use the app (the OAuth authorization and token issuance of the client API), and on setups that require email confirmation, only those who have confirmed their email address.

A new user who can use the app at once goes from the sign-up page straight into the app, to a welcome step that asks for
a display name and an avatar. The home timeline then shows a checklist of first steps and suggestions of people to
follow ([suggestions](https://mycroblog.dev/next/operations/instance-settings/#suggestions-of-accounts)). "Continue" on the page that confirms an email
address leads to the same welcome step.

An administrator created with `my admin create` counts as approved and confirmed.

## Email confirmation

The setting `mail` ([configuration reference](https://mycroblog.dev/next/reference/configuration/#mail)) selects how mail is sent.
SMTP examples, DNS setup and how to read delivery failures are in [sending email](https://mycroblog.dev/next/operations/email/).

- `mail = smtp`: the server sends a confirmation mail on registration. The link is valid for 24 hours and works once.
  Opening the link shows a page with a confirm button, and the address is confirmed when the user presses it (so that scanners that prefetch links in mail do not consume the token).
  After signing in, the user can have the mail sent again up to 3 times an hour.
  The connection to the SMTP server is always encrypted with STARTTLS, and the server verifies the certificate before authenticating and sending. It never sends to a server that does not offer STARTTLS.
- `mail = none` (default): the server sends no mail and writes `mail not sent (mail = none)` with the category of the message to the server log. Only with `profile = development` does the line also hold the address and the body, including the confirmation link.
  Because mail never reaches the user, the server asks for a moderator's approval instead of email confirmation.
  So a registration in `open` mode also starts as waiting for approval, and an unconfirmed email address does not block use of the app.

The confirmation token is recorded nowhere except this development log line (access logs do not record query strings). The database stores only the SHA-256 of the token.

## Registration limited to login providers

While the instance setting `login_providers_only` is on and at least one [login provider](https://mycroblog.dev/next/operations/login-providers/#limit-sign-in-to-login-providers) is enabled, the sign-up page has no password form and offers only the providers that allow sign-ups; an invite code in the link carries through to the provider's sign-up form. A registration with a password is refused, whatever the form holds. With no provider that allows sign-ups, registration reads as `closed`. With no enabled provider, the setting does not apply.

## Password reset and change

While the instance setting `login_providers_only` applies, reset links and setting or changing a password are refused ([what the limit does](https://mycroblog.dev/next/operations/login-providers/#limit-sign-in-to-login-providers)).

- `mail = smtp`: when a user enters an email address under "Forgot your password?" on the sign-in page, the server sends a link for setting a new password to the user whose primary address it is.
  The page's answer is the same whether or not an account exists. The link is valid for 1 hour and works once, and it stops working if the password changes by another route in the meantime.
  Requests are limited to 5 per 30 minutes per client IP address, and mail to 3 per hour per address (a request over a limit sends nothing and gets the same answer). When CAPTCHA is enabled, this form is verified too.
- `mail = none`: the page says that it cannot send a link and tells the user to ask an administrator. The administrator issues a link on the account's Management page of the admin screens, or with `my admin account password-reset-link @alice`, and gives it to the user ([moderation](https://mycroblog.dev/next/operations/moderation/)).
- A signed-in user can change the password under "Password" in settings by entering the current password (wrong entries are limited to 5 per hour per user).
- A reset or a change revokes the user's other sessions and app tokens (a change from settings keeps only the app that made the change). Passkeys and two-factor authentication stay.
  A sign-in that waits for its two-factor code, and an app authorization not yet completed, stop working too: the user starts them again.
  With `mail = smtp`, the server also emails the user to say the password changed.

## Invite codes

Invites work in the `open`, `approval` and `invite` modes. Staff invites are made with the CLI, the moderation screens and the admin API below; members can also make their own invites ([member invites](#member-invites)).
In `closed` mode no invite can be created and none works.

```sh
my invite create                          # single use, expires in 7 days
my invite create -max-uses 10 -expires-in 72h
my invite create -max-uses 0 -expires-in 0  # no limit on uses or time
my invite list                            # newest first; states: usable / revoked / expired / used up
my invite revoke <code>
```

- `create` prints the code (16 characters) and the link to the sign-up page with the code filled in (`https://<host>/auth/sign_up?invite=<code>`).
- Codes are matched ignoring case, spaces and hyphens.
- Even when several people register at once, a code is never used beyond its limit (a unique constraint on `invite_redemptions`).
- A revoked, expired or used-up code all give the same error (an unusable invite).
- Besides the CLI, you can create, list and revoke invites in the web client's Moderation screens ("Invites", `/moderation/invites`) and through the client API
  (`GET` / `POST /api/v1/admin/invites` and `POST /api/v1/admin/invites/{id}/revoke`). Both need the role permission `manage_invites`
  (the built-in `moderator` does not have it, so to delegate this, create a role with that permission and grant it).
  A service that hands out invites by itself calls the same API with a token of the scope `admin:manage_invites` ([letting another service use the admin API](https://mycroblog.dev/next/operations/moderation/#letting-another-service-use-the-admin-api)).
  "Create an invite" on the list opens the form (`/moderation/invites/new`), which shows the code and the sign-up link of the new invite.
  The list shows every invite's code, who created it, how many signed up with it, its end and its state; pick invites and choose "Revoke", which asks first.
- The list shows every invite, the staff's and the members', with who created it (`created_by`) and how (`creator_kind`: `staff` or `member`). The holders of `manage_invites` can revoke any of them.
- The account's Review page of the moderation screens (`GET /api/v1/admin/accounts/{id}`, permission `manage_accounts`) shows the invite the account signed up with and who created it, the person who invited the user.
- Creating and revoking an invite is recorded in the audit log (`invite_created`, `invite_revoked`) from the screen, the API and the CLI alike. The target name is the first 4 characters of the code (`ABCD…`); the full code is not copied to the audit log.
  Revoking an already revoked invite changes nothing, so it is not recorded.

## Member invites

Members can create invites of their own, besides the staff.
Who may is the instance setting `invite_creators` ([instance settings](https://mycroblog.dev/next/operations/instance-settings/)):

- `permitted` (default): only the users whose roles have the permission `create_invites`. Only the built-in `admin` role has it by default. You can add it to a role you grant by hand, or to the role of a [supporter plan](https://mycroblog.dev/next/operations/supporters/), so that supporters can invite people.
- `everyone`: every signed-in local user.

Either way, a user whose account is suspended or limited, or whose registration is not approved, cannot create invites, and nobody can while the registration mode is `closed`.
The holders of `manage_invites` keep making staff invites, which none of the limits below apply to.

A member creates, lists and revokes their own invites, and copies the link of a usable one, in the web client's settings ("Invites", `/settings/invites`), or through the client API (`GET` / `POST /api/v1/invites` and `POST /api/v1/invites/{id}/revoke`).
The settings list the page only for a user who can create invites now; a user who cannot still opens it from its address, where it says why, to revoke the invites they made.
The list says, for each invite, whether it is usable, revoked, expired, used up, or not usable while its creator cannot create invites.

Limits, also instance settings, apply to member invites only.
Administrators change them, and `invite_creators`, under "Member invites" on the "Registration" page of the server settings (`/admin/settings/registration`):

| Setting | Meaning | Default | Range |
| --- | --- | --- | --- |
| `member_invite_max_active` | How many usable invites (not revoked, expired or used up) one member may hold at once | `5` | 0-100 (0: members cannot create invites) |
| `member_invite_max_uses` | How many people may sign up with one invite | `10` | 1-1,000 |
| `member_invite_max_lifetime_seconds` | How long one invite may work, in seconds | `2592000` (30 days) | 3,600 (1 hour) to 31,536,000 (365 days) |

- A member chooses the uses and the lifetime within the limits; without a choice, an invite allows 1 sign-up and works for 7 days (or less, when a limit is lower). An invite without a limit on uses or time cannot be created.
- Lowering a limit does not change existing invites; it applies to the next invite created.
- Every sign-up with a member's invite checks that its creator can still create invites. When the creator lost `create_invites` (for example, their plan ended), `invite_creators` went back to `permitted`, or the account was suspended, limited or deleted, the invite does not work and the sign-up page says it is not valid.
  The invite itself is not changed, so it works again, within its expiry, when the creator may invite again.
- A member's create and revoke are recorded in the audit log as `invite_created` and `invite_revoked`, with the member as the actor.

In `approval` mode, a usable invite approves the new user at once: the person who invited them stands in for the moderators' review.
With `invite_creators = everyone`, every user can therefore let people in without review, which weakens the approval mode.
If you rely on review, keep `permitted` and give `create_invites` only to people you trust, or keep `member_invite_max_active` and `member_invite_max_uses` low.

## Approving and rejecting

```sh
my registration list                      # waiting for approval (longest wait first); shows the reason and whether the email is confirmed
my registration list -state rejected
my registration approve alice
my registration reject -note "spam" bob
```

- The argument is the username of a local account (the leading `@` may be omitted).
- Only registrations that are waiting for approval can be decided. For a decided registration, or a user created without the sign-up page (`my admin create`), the command changes nothing and exits with code 1.
- Exit code 2 means a wrong argument.

The same decisions can be made from the admin screens (the client API). All of them need the `manage_accounts` permission.
In the web client, Moderation → Registrations (`/moderation/registrations`) lists the registrations waiting for approval with their email address, whether it is confirmed and the reason for joining; pick them and choose "Approve" or "Reject", which asks first, with a note for the moderators. A one-person server does not show it.

| Operation | What it does |
| --- | --- |
| `GET /api/v1/admin/registrations` | Registrations waiting for approval (longest wait first). Returns the ID of the registration, the reason for joining, the email address and whether it is confirmed, and the local account |
| `POST /api/v1/admin/registrations/{id}/approve` | Approves. The body `{"note": "..."}` is optional. The answer shows the note as `decision_note`, and an answer on a decided registration has no email address |
| `POST /api/v1/admin/registrations/{id}/reject` | Rejects. The body is the same as for `approve` |

- This is the same use case as the CLI, and it records the decision in `registration_decisions` and the audit log (`registration_approved`, `registration_rejected`). The actor of a CLI decision is `cli`; the actor of an API decision is the moderator who decided.
- Deciding an already decided registration changes nothing and returns the current state (if two people decide at once, only one decision is recorded). A user created without the sign-up page gives 404.

## Sign-up blocks

Blocks reject registrations from the sign-up page, or switch them to approval, by email domain, email address or IP range.

```sh
my admin signup-block create -kind email_domain spam.example          # also applies to subdomains; a U-label works too
my admin signup-block create -kind ip_range -severity require_approval -duration 720h 192.0.2.0/24
my admin signup-block create -kind email_hash spammer@example.com     # only a hash of the address is kept
my admin signup-block list -active
my admin signup-block lift <block id>
```

- A registration that matches a block with `-severity reject` (the default) is refused, and one that matches `require_approval` starts as waiting for approval whatever the registration mode is. When several match, the stronger one applies. The sign-up page does not show the reason for a rejection.
- `email_hash` is matched against the address in lower case, without the part of the local part from the first `+`. An IP range is matched against the registration IP (the same value as `registration_origins`) and never applies to a registration whose IP is unknown.
- Expired and lifted blocks have no effect. Adding and lifting are recorded in the audit log (`signup_block_added`, `signup_block_lifted`).
- When you ban a local account with `-block-email` (`block_email: true` in the API), the server also creates an `email_hash` block for that user's email address.

For a list of thousands of entries, such as the domains of disposable email services, add them in bulk with `import` from a file (`-` for standard input). Every value gets the same kind, severity, comment and duration.

```sh
my admin signup-block import -kind email_domain -comment "disposable email" disposable.txt
```

- The list has one value per line (the same form as `<value>` of `add`), or CSV rows whose first column is the value. Blank lines and lines that start with `#` are skipped. One import takes up to 10,000 entries.
- The command prints how many were added and, for each row it did not add, the line number, the value and the reason. The reason is `invalid` (not a valid value of that kind), `duplicate` (the same normal form as an earlier row of the same list) or `already_blocked` (a block of the same kind and value that is equally or more severe is in effect).
- Each added block is recorded in the audit log (`signup_block_added`) as with `add`, and can be lifted one by one.
- The import writes in transactions of a few hundred, so if it fails midway, what was added before stays. Importing the same list again adds only the rest.
- The software ships no list and does not fetch one from a URL periodically. You fetch and update public lists (such as disposable-email-domains on GitHub) yourself and import the updated list again.

The same operations are available from the admin screens (the client API). All of them need the `manage_accounts` permission.
In the web client, open Moderation → Sign-up blocks (`/moderation/signup-blocks`). The list shows each block's value, kind, state and end, in effect or all;
"Add a block" opens the form (`/moderation/signup-blocks/new`), "Add from a list" imports a list and shows the lines it skipped (`/moderation/signup-blocks/import`),
and choosing a value opens the block's page with its effect and comment, where "Lift" ends it.

| Operation | What it does |
| --- | --- |
| `GET /api/v1/admin/signup_blocks` | Lists blocks (newest first). Filter with `kind` and `active` |
| `POST /api/v1/admin/signup_blocks` | Adds a block. The body has `kind`, `value`, `severity`, `comment` and `expires_in` (seconds, at most ten years) |
| `POST /api/v1/admin/signup_blocks/import` | Adds blocks from a list. The body has `kind`, `text` (the list), `severity`, `comment` and `expires_in`. The response has `added`, the number added, and `skipped`, the rows not added (`line`, `value`, `reason`) |
| `GET /api/v1/admin/signup_blocks/{id}` | Returns one block |
| `POST /api/v1/admin/signup_blocks/{id}/lift` | Lifts a block. A block already lifted stays as it is |
