Admin-managed registration¶

Overview¶

When JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION = True the library enables a closed registration flow where existing admins invite users. In this mode, the EMAIL_VERIFICATION setting is effectively ignored for invited users: the email is always verified during the verification GET step, never at the password-set step.

Admin creates the user via POST /registration/user-register/.
The invited user receives a verification email.
Upon clicking the verification link (GET /registration/verification/<key>/), a one-time access token is stored in an HTTP-only cookie and the user is redirected to the UI path configured in PASSWORD_SET_REDIRECT.
The UI submits POST /registration/set-password/ with new_password1/new_password2 to set the password and receive tokens.

Endpoints¶

POST /registration/user-register/ (name: rest_user_register) — Allowed to roles defined by JWT_ALLAUTH_REGISTRATION_ALLOWED_ROLES (defaults to [STAFF_CODE, SUPER_USER_CODE]).
GET /registration/verification/<key>/ (name: account_confirm_email) — Confirms the email and drops a set_password_access_token cookie when admin-managed is enabled.
POST /registration/set-password/ (name: rest_set_password) — Reads the one-time token from cookie, sets password, returns tokens. Throttled with UserRateThrottle.

Payloads¶

Admin creates a user:

{
  "email": "writer@demo.com",
  "role": 300,
  "first_name": "Optional",
  "last_name": "Optional"
}

Set password after verification:

{
  "new_password1": "********",
  "new_password2": "********"
}

Behavior¶

Duplicate email: - If an existing verified EmailAddress is found for the email, registration fails with 400 on email. - If only non-verified entries exist, they are removed and a new user is created (previous user loses the associated EmailAddress), allowing coexistence.
Response from user-register is a 201 with an empty body.

Settings¶

JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION (default: False)
JWT_ALLAUTH_REGISTRATION_ALLOWED_ROLES (default: [STAFF_CODE, SUPER_USER_CODE]) — list of role codes allowed to register users.
PASSWORD_SET_REDIRECT — UI path for the set-password form
PASSWORD_SET_COOKIE_HTTP_ONLY (default: True)
PASSWORD_SET_COOKIE_SECURE (default: not DEBUG)
PASSWORD_SET_COOKIE_SAME_SITE (default: 'Lax')
PASSWORD_SET_COOKIE_MAX_AGE (default: 3600 * 24 seconds)

Permissions¶

RegisterUsersPermission — grants access to user-register when the requester’s role is in JWT_ALLAUTH_REGISTRATION_ALLOWED_ROLES. Defaults to allowing STAFF_CODE and SUPER_USER_CODE.

Email verification behavior¶

The verification GET confirms the email in admin-managed mode and issues a one-time token, then redirects to the password set UI.
The verification link allows multiple accesses (e.g. by email scanners) and is only invalidated once the password is successfully set.
The verification link validity is determined by ACCOUNT_EMAIL_CONFIRMATION_EXPIRE_DAYS (default: 3 days).
The set-password endpoint does not alter email verification status.

Email templates¶

The verification email sent for admin-managed invitations uses a dedicated template whose defaults are:
- Subject: email/admin_invite/email_subject.txt
- HTML body: email/admin_invite/email_message.html

Error templates¶

When the verification link is invalid or expired, a friendly error page is shown:
- HTML body: registration/verification_failed.html
You can override these by configuring JWT_ALLAUTH_TEMPLATES with ADMIN_EMAIL_VERIFICATION_SUBJECT, ADMIN_EMAIL_VERIFICATION and EMAIL_VERIFICATION_FAILED_TEMPLATE. See settings.py for details.

MFA REQUIRED Integration¶

When JWT_ALLAUTH_MFA_TOTP_MODE = 'required' and JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION = True, the admin-managed registration flow is extended to enforce MFA setup and provides immediate token issuance after MFA activation. This mirrors the MFA bootstrap behavior described in Multi-Factor Authentication (MFA TOTP).

Flow with MFA REQUIRED:

Admin creates user via POST /registration/user-register/ → User created, no tokens
User receives verification email
User clicks verification link → One-time token issued in cookie

User sets password via POST /registration/set-password/ → Returns MFA setup challenge instead of tokens:

{
    "mfa_setup_required": true,
    "setup_challenge_id": "a1b2c3d4-e5f6-4a8b-9c0d-e1f2a3b4c5d6",
    "detail": "Password set. Please configure MFA to complete registration."
}

User accesses POST /mfa/setup/ with setup_challenge_id (no authentication required)
User accesses POST /mfa/activate/ with setup_challenge_id and TOTP code
Tokens are issued after successful MFA activation (using the same response helper as login, respecting cookie configuration)
User can now login normally

Key Differences:

set-password endpoint returns mfa_setup_required + setup_challenge_id instead of tokens
Users cannot receive tokens until MFA is configured
The setup_challenge_id allows temporary access to MFA setup endpoints without full authentication
After successful MFA activation (POST /mfa/activate/), tokens are issued immediately (unlike self-service registration, where users must re-login)
This ensures all users go through MFA setup before gaining any access, preventing security bypasses
Users immediately have access after MFA activation without needing to re-login

Settings Impact:

The following settings continue to work as expected: - JWT_ALLAUTH_REFRESH_TOKEN_AS_COOKIE — Controls token delivery method after MFA activation (respects this setting) - PASSWORD_SET_COOKIE_* — Controls one-time token cookie during password setup - JWT_ALLAUTH_MFA_TOTP_MODE — Must be set to 'required' for this behavior - JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION — Must be set to True for tokens to be issued immediately after MFA activation

Important: Immediate Token Issuance

When both JWT_ALLAUTH_MFA_TOTP_MODE = 'required' and JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION = True:

/mfa/activate/ endpoint returns tokens immediately after successful TOTP verification
This means users do not need to re-login after MFA setup
This improves user experience for invited/admin-managed workflows by providing seamless onboarding

This behavior is different from self-service registration, where /mfa/activate/ returns only recovery codes and the user must re-login to obtain tokens.