Self-service account creation

POST

/auth/register

• Local development behind nginx (port 8088 by default)

Anonymous endpoint. Creates a new local account when sysconfig auth.self_registration.enabled is true, otherwise returns 403. Username must match ^[a-zA-Z0-9_-]{3,32}$ + be globally unique. Password must satisfy the policy block. Email is required.

When auth.self_registration.require_email_verification is true (the default), the user is created with email_verified_at IS NULL and the response is 202 — they cannot sign in until they click the verification link in the email we send. With verification off, the response is 200 + a session cookie.

Rate-limited by both IP and attempted email so spam clients can’t enumerate.

Request Body ^required

Self-registration payload. Validation is server-side authoritative; the frontend mirrors the same regexes for early UX feedback.

object

username

required

string

>= 3 characters <= 32 characters /^[a-zA-Z0-9_-]+$/

email

required

string format: email

password

required

Must satisfy the install’s sysconfig password policy.

string format: password

fullname

Optional display name; defaults to the username when empty.

string

<= 200 characters

Responses

200

Account created + signed in (verification disabled).

object

ref

required

integer format: int64

username

required

string

fullname

string

nullable

email

string

nullable

usergroup

integer format: int64

nullable

auth_method

required

How the caller was authenticated for this request.

string

Allowed values: session token

language

User’s language pref (BCP47). Empty string = follow system / browser. Joined from user_profiles at /auth/me time so the frontend can hydrate the language store on first paint without a separate round-trip.

string

theme

User’s theme pref. Empty string = follow system. Same “join on /auth/me” rationale as language.

string

Allowed values: "" light dark

impersonated_by

Non-null when the session was minted via POST /admin/users/{ref}/impersonate. Carries the acting admin’s ref + username so the persistent “you are acting as @target” banner can render without a separate round-trip.

object

ref

required

integer format: int64

username

required

string

202

Account created; verification email sent. Caller must verify before login.

202 response when require_email_verification is on. The caller is not signed in yet; the verification link they receive by email completes the flow.

object

user_ref

required

integer format: int64

email

required

string format: email

message

required

Human-readable next-step prompt.

string

400

Malformed request

object

error

required

Human-readable error summary

string

Example

the request could not be completed

403

Self-registration is disabled on this install.

object

error

required

Human-readable error summary

string

Example

the request could not be completed

409

Username or email already in use.

object

error

required

Human-readable error summary

string

Example

the request could not be completed

429

Rate-limited; retry after a brief pause.

object

error

required

Human-readable error summary

string

Example

the request could not be completed