16.1.1.21. Register endpoints

The register REST API lets an unauthenticated user create a new user account in an editable user resolver. Successful registration creates the user, issues a registration token, and emails the registration key to the user. The user can then complete enrollment by authenticating with their chosen password and that registration key.

Both endpoints are anonymous (no auth header). Registration is gated by a set of policies in scope register — a destination resolver is required, plus smtpconfig for sending the email, optionally realm, registration_body and requiredemail. See Register Policy for the full list.

GET /register

Return whether self-registration is enabled on this server. The result is True when at least one policy in scope register configures a resolver action; otherwise False. The WebUI uses this to decide whether to show the registration button.

This endpoint is anonymous — no authentication header is required.

Status Codes:

  • 200 OK – result.value is True if registration is configured, False otherwise.

POST /register

Register a new user in a configured user resolver. The destination resolver must be editable (e.g. an SQL resolver). On success the call creates the user account, issues a registration token, and emails the registration key to email.

If the email cannot be sent, the just-created user and token are removed before the request fails — failed registrations leave no state behind.

This endpoint is anonymous. Registration depends on policies in scope register:

  • resolver (required) — the editable resolver to create the user in.

  • smtpconfig (required) — identifier of the SMTP server used to send the registration email.

  • realm (optional) — the realm to register in. Defaults to the default realm.

  • registration_body (optional) — text template for the email body; {regkey} is substituted with the registration key.

  • requiredemail (optional) — restricts which email addresses may register (enforced by the required_email prepolicy).

  • hide_specific_error_message (optional) — masks specific error messages with a generic registration error.

JSON Parameters:

  • username – login name of the new user (required).

  • givenname – given name (required).

  • surname – surname (required).

  • email – email address (required); registration key is sent here.

  • password – password the user will authenticate with (required).

  • mobile – mobile phone number.

  • phone – land line phone number.

Status Codes:

  • 200 OK – result.value is True if the user was created and the registration email was sent.

  • 400 Bad Request – registration prerequisites not met (no resolver configured, SMTP not configured, username already registered, email rejected by requiredemail, send failure).