API endpoints¶

Authentication¶

/login/ (POST)¶

Request

Location	Field	Description
Body (JSON)	`email`	User’s email address.
Body (JSON)	`password`	User’s password.

Response

Location	Field	Description
Body (JSON)	`access`	JWT access token.
Cookie (HTTP-only)	`refresh_token`	JWT refresh token, stored by default in the `refresh_token` cookie.
Body (JSON, optional)	`mfa_required`	When MFA is enabled and the user has it configured. The response contains a `challenge_id` instead of tokens so you can complete login via the MFA verification endpoints.
Body (JSON, optional)	`mfa_setup_required`	When MFA mode is REQUIRED but the user has not set it up yet. The response contains a `setup_challenge_id` to bootstrap MFA setup.

URL Name: rest_login

Note

Django Rest Framework throttling enabled, see: https://www.django-rest-framework.org/api-guide/throttling/

/refresh/ (POST)¶

Request

Location	Field	Description
Cookie (HTTP-only, default)	`refresh_token`	Refresh token read automatically from the `refresh_token` cookie when `JWT_ALLAUTH_REFRESH_TOKEN_AS_COOKIE = True` (default).
Body (JSON, optional)	`refresh`	Refresh token sent explicitly in the request body when you are not using cookies (`JWT_ALLAUTH_REFRESH_TOKEN_AS_COOKIE = False`).

Response

Location	Field	Description
Body (JSON)	`access`	New JWT access token.
Cookie (HTTP-only, default)	`refresh_token`	New refresh token stored in the `refresh_token` cookie when cookies are enabled.
Body (JSON, optional)	`refresh`	New refresh token returned in the response body when cookies are disabled.

URL Name: token_refresh

/logout/ (POST) `[Authenticated]`¶

Request

Location	Field	Description
Cookie (HTTP-only, default)	`refresh_token`	Refresh token taken automatically from the `refresh_token` cookie when `JWT_ALLAUTH_REFRESH_TOKEN_AS_COOKIE = True`.
Body (JSON, optional)	`refresh`	Refresh token to invalidate when you are not using cookies (`JWT_ALLAUTH_REFRESH_TOKEN_AS_COOKIE = False`).

Response

Status	Description
`200 OK`	User successfully logged out and the refresh token is revoked.

URL Name: rest_logout

/logout-all/ (POST) `[Authenticated]`¶

Request

Location	Description
N/A	No request body or query parameters.

Response

Status	Description
`200 OK`	User successfully logged out from all devices.

/password/reset/ (POST)¶

Request

Location	Field	Description
Body (JSON)	`email`	Email address to send the reset link to.

Response

Status	Description
`200 OK`	JSON response with a `detail` message indicating that the reset e-mail has been sent.

URL Name: rest_password_reset

Note

Django Rest Framework throttling enabled, see: https://www.django-rest-framework.org/api-guide/throttling/

Warning

Requires an email server configured.

/password/reset/confirm/<str:uidb64>/<str:token>/ (GET)¶

Response

Location	Description
HTML page	Redirects to the UI configured by `PASSWORD_RESET_REDIRECT` or renders the default password reset form.

URL Name: password_reset_confirm

Note

uid and token are sent in email after calling /password/reset/

/password/reset/default/ (GET)¶

Response

Location	Description
HTML page	Renders the default password reset form.

URL Name: default_password_reset

Note

Used when PASSWORD_RESET_REDIRECT is not configured.

/password/reset/complete/ (GET)¶

Response

Location	Description
HTML page	Renders the password reset complete page.

URL Name: jwt_allauth_password_reset_complete

Note

Used when PASSWORD_RESET_REDIRECT is not configured.

/password/reset/set-new/ (POST) `[Cookie]`¶

Request

Location	Field	Description
Cookie (HTTP-only)	`password_reset_access_token`	One-time access token set as a secure cookie when the user follows the reset link.
Body (JSON)	`new_password1`	New password.
Body (JSON)	`new_password2`	Password confirmation.

Response

Status	Description
`200 OK`	Password updated successfully. Returns new JWT tokens and a `detail` message.

URL Name: password_reset_confirm

/password/change/ (POST) `[Authenticated]`¶

Request

Location	Field	Description
Body (JSON)	`new_password1`	New password.
Body (JSON)	`new_password2`	Password confirmation.
Body (JSON, optional)	`old_password`	Current password (required if `OLD_PASSWORD_FIELD_ENABLED = True`).

Response

Status	Description
`200 OK`	Password changed successfully. Optionally logs the user out of other sessions when `LOGOUT_ON_PASSWORD_CHANGE = True`.

URL Name: rest_password_change

Note

OLD_PASSWORD_FIELD_ENABLED = True to use old_password (default).

Note

LOGOUT_ON_PASSWORD_CHANGE = True to logout from the remaining sessions.

/user/ (GET, PUT, PATCH) `[Authenticated]`¶

Request (PUT/PATCH)

Location	Field	Description
Body (JSON)	`email`	User email address.
Body (JSON, optional)	`first_name`	User’s first name.
Body (JSON, optional)	`last_name`	User’s last name.

Response

Location	Field	Description
Body (JSON)	`email`	User’s email address.
Body (JSON)	`first_name`	User’s first name.
Body (JSON)	`last_name`	User’s last name.

URL Name: rest_user_details

Registration¶

/registration/ (POST)¶

Request

Location	Field	Description
Body (JSON)	`email`	Email address for the new user.
Body (JSON)	`password1`	Password.
Body (JSON)	`password2`	Password confirmation.
Body (JSON, optional)	`first_name`	First name.
Body (JSON, optional)	`last_name`	Last name.

Response

Location	Field	Description
Body (JSON, optional)	`key`	Authentication token when email verification is disabled.
Body (JSON)	`email`	Registered email address.
Body (JSON)	`detail`	Message indicating that a verification e-mail has been sent when email verification is enabled.

URL Name: rest_register

Note

Disabled when JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION = True (the open registration endpoint is removed in admin-managed mode).

/registration/user-register/ (POST) `[Admin role]`¶

Request

Location	Field	Description
Body (JSON)	`email`	Email address for the new user.
Body (JSON)	`role`	User role to assign to the new user.
Body (JSON, optional)	`first_name`	First name.
Body (JSON, optional)	`last_name`	Last name.

Response

Status	Description
`201 Created`	Verification e-mail sent to the invited user.

URL Name: rest_user_register

Note

Enabled when JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION = True. Keeps the default /registration/ endpoint unchanged unless you enable this setting.

/registration/verification/<str:key>/ (GET)¶

Response

Location	Description
Redirect / HTML page	Redirects to the UI configured by `EMAIL_VERIFIED_REDIRECT` or renders the verified page.

URL Name: account_confirm_email

Note

Disabled when EMAIL_VERIFICATION = False.

/registration/set-password/ (POST) `[Cookie]`¶

Request

Location	Field	Description
Cookie (HTTP-only)	`set_password_access_token`	One-time access token set as a secure cookie after the invited user clicks the verification link.
Body (JSON)	`new_password1`	Password.
Body (JSON)	`new_password2`	Password confirmation.

Response

Status	Description
`200 OK`	Password set successfully. Returns JWT tokens or an MFA setup challenge depending on the MFA configuration.

URL Name: rest_set_password

Note

Only available when JWT_ALLAUTH_ADMIN_MANAGED_REGISTRATION = True. This endpoint is reached after the invited user clicks the verification link. The GET verification drops a one-time access token in the set_password_access_token cookie and redirects to the UI configured by PASSWORD_SET_REDIRECT. Throttled with UserRateThrottle by default.

/registration/account_email_verification_sent/ (GET)¶

Response

Location	Description
HTML page	Renders the email verification sent notification page.

URL Name: account_email_verification_sent

Note

Disabled when EMAIL_VERIFICATION = False.

/registration/verified/ (GET)¶

Response

Location	Description
HTML page	Renders the email verified confirmation page.

URL Name: jwt_allauth_email_verified

Note

Disabled if EMAIL_VERIFIED_REDIRECT is defined or EMAIL_VERIFICATION = False.

Multi-Factor Authentication (MFA)¶

Note

Requires allauth.mfa in INSTALLED_APPS of your Django project and database migrations applied.

/mfa/setup/ (POST) `[Authenticated]`¶

Request

Location	Description
N/A	No request body. The authenticated user (or MFA setup challenge) is used to determine which account to configure.

Response

Location	Field	Description
Body (JSON)	`provisioning_uri`	OTPAuth URI for QR code generation.
Body (JSON)	`secret`	Base32-encoded secret key.
Body (JSON)	`qr_code`	SVG formatted QR code image.

URL Name: mfa_setup

/mfa/activate/ (POST) `[Authenticated]`¶

Request

Location	Field	Description
Body (JSON)	`code`	TOTP code from the authenticator app.
Body (JSON, optional)	`setup_challenge_id`	Challenge ID used in MFA bootstrap flows (login or registration) when MFA mode is `required`.

Response

Location	Field	Description
Body (JSON)	`recovery_codes`	List of one-time recovery codes.
Body (JSON, optional)	`success`	Indicates successful activation (always `True` on success).
Body (JSON, optional)	`access`	Access token issued when MFA mode is `required` and activation is performed using `setup_challenge_id`.
Body (JSON, optional)	`refresh`	Refresh token issued when MFA mode is `required` and activation is performed using `setup_challenge_id` (may be delivered via HTTP-only cookie depending on settings).

URL Name: mfa_activate

/mfa/verify/ (POST)¶

Request

Location	Field	Description
Body (JSON)	`challenge_id`	MFA challenge ID from the login attempt.
Body (JSON)	`code`	TOTP code from the authenticator app.

Response

Location	Field	Description
Body (JSON)	`access`	JWT access token.
Cookie (HTTP-only)	`refresh_token`	JWT refresh token set in the `refresh_token` cookie (by default).

URL Name: mfa_verify

/mfa/verify-recovery/ (POST)¶

Request

Location	Field	Description
Body (JSON)	`challenge_id`	MFA challenge ID from the login attempt.
Body (JSON)	`recovery_code`	One-time recovery code.

Response

Location	Field	Description
Body (JSON)	`access`	JWT access token.
Cookie (HTTP-only)	`refresh_token`	JWT refresh token set in the `refresh_token` cookie (by default).

URL Name: mfa_verify_recovery

/mfa/deactivate/ (POST) `[Authenticated]`¶

Request

Location	Field	Description
Body (JSON)	`password`	User’s password for confirmation.

Response

Status	Description
`200 OK`	MFA TOTP authenticator (and recovery codes) deactivated for the user.

URL Name: mfa_deactivate

/mfa/authenticators/ (GET) `[Authenticated]`¶

Request

Location	Description
N/A	No request body or query parameters.

Response

Location	Description
Body (JSON)	Array of authenticator objects with details about enabled MFA devices.

URL Name: mfa_authenticators

Note

MFA TOTP can be configured with the JWT_ALLAUTH_MFA_TOTP_MODE setting:

'disabled' (default): MFA endpoints return 403 Forbidden when accessed.
'optional': Users can set up MFA but it’s not required during login.
'required': Users must set up MFA and provide TOTP code during login. Deactivation is blocked.

API endpoints¶

Authentication¶

/login/ (POST)¶

/refresh/ (POST)¶

/logout/ (POST) [Authenticated]¶

/logout-all/ (POST) [Authenticated]¶

/password/reset/ (POST)¶

/password/reset/confirm/<str:uidb64>/<str:token>/ (GET)¶

/password/reset/default/ (GET)¶

/password/reset/complete/ (GET)¶

/password/reset/set-new/ (POST) [Cookie]¶

/password/change/ (POST) [Authenticated]¶

/user/ (GET, PUT, PATCH) [Authenticated]¶

Registration¶

/registration/ (POST)¶

/registration/user-register/ (POST) [Admin role]¶

/registration/verification/<str:key>/ (GET)¶

/registration/set-password/ (POST) [Cookie]¶

/registration/account_email_verification_sent/ (GET)¶

/registration/verified/ (GET)¶

Multi-Factor Authentication (MFA)¶

/mfa/setup/ (POST) [Authenticated]¶

/mfa/activate/ (POST) [Authenticated]¶

/mfa/verify/ (POST)¶

/mfa/verify-recovery/ (POST)¶

/mfa/deactivate/ (POST) [Authenticated]¶

/mfa/authenticators/ (GET) [Authenticated]¶

/logout/ (POST) `[Authenticated]`¶

/logout-all/ (POST) `[Authenticated]`¶

/password/reset/set-new/ (POST) `[Cookie]`¶

/password/change/ (POST) `[Authenticated]`¶

/user/ (GET, PUT, PATCH) `[Authenticated]`¶

/registration/user-register/ (POST) `[Admin role]`¶

/registration/set-password/ (POST) `[Cookie]`¶

/mfa/setup/ (POST) `[Authenticated]`¶

/mfa/activate/ (POST) `[Authenticated]`¶

/mfa/deactivate/ (POST) `[Authenticated]`¶

/mfa/authenticators/ (GET) `[Authenticated]`¶