Headless API Endpoints - Django Allauth

The headless API provides a complete REST interface for authentication flows. All endpoints are versioned under /v1/ and support both browser and app clients.

Base URL Structure

Endpoints are organized by client type:

Browser client: /_allauth/browser/v1/
App client: /_allauth/app/v1/

The client type determines authentication mechanisms:

Browser: Uses session cookies
App: Uses token-based authentication (session tokens or JWTs)

Configuration

GET /config

Returns the current authentication configuration. Response Fields

object

Account configuration settings

Show properties

Available login methods: email, username, or phone

Whether new user registration is enabled

boolean

Whether email verification uses codes instead of links

Whether passwordless login via code is enabled

boolean

Whether password reset uses codes instead of links

string

Legacy field: email, username, or username_email

Example Response

{
  "account": {
    "login_methods": ["email"],
    "is_open_for_signup": true,
    "email_verification_by_code_enabled": false,
    "login_by_code_enabled": false,
    "password_reset_by_code_enabled": false,
    "authentication_method": "email"
  }
}

Authentication

Authenticate a user with credentials. Request Body

string

User’s email address (when email login is enabled)

string

User’s username (when username login is enabled)

string

User’s phone number in E.164 format (when phone login is enabled)

string

required

User’s password

Response Returns an AuthenticationResponse with user data and session information. Example Request

{
  "email": "user@example.com",
  "password": "secretpassword"
}

Rate Limiting: This endpoint is rate-limited per the login action.

string

required

User’s email address

string

Desired username (if username field is configured)

string

Account password (required unless passwordless signup is configured)

Response Returns an AuthenticationResponse. May include pending verification flows. Status Codes

200 OK: User created and authenticated
403 Forbidden: Signup is disabled
409 Conflict: User is already authenticated

Rate Limiting: This endpoint is rate-limited per the signup action.

GET /auth/session

Retrieve the current session state. Response Returns an AuthenticationResponse with current user information or 401 if not authenticated.

DELETE /auth/session

Log out the current user. Response Returns an AuthenticationResponse with is_authenticated: false.

POST /auth/code/request

Request a login code for passwordless authentication. Request Body

string

Email address to send the code to

string

Phone number to send the code to (E.164 format)

Response Returns an AuthenticationResponse with a pending login_by_code flow.

POST /auth/code/confirm

Confirm a login code. Request Body

string

required

The verification code received via email or SMS

Response Returns an AuthenticationResponse with authenticated user data. Status Codes

200 OK: Code verified, user authenticated
409 Conflict: No pending login code verification

POST /auth/reauthenticate

Re-authenticate the current user (for sensitive operations). Request Body

string

required

User’s current password

Response Returns an AuthenticationResponse. Rate Limiting: This endpoint is rate-limited per the reauthenticate action.

Email Verification

GET /auth/email/verify

Verify an email address. Headers

string

required

The verification key from the email link or code

Response Fields

string

The email address being verified

object

User information

boolean

Whether this verification is part of an authentication flow

Status Codes

200 OK: Verification key is valid
409 Conflict: No pending verification

POST /auth/email/verify

Complete email verification. Request Body

string

required

The verification key

Response Returns an AuthenticationResponse. If part of login/signup flow, the user will be authenticated.

POST /auth/email/verify/resend

Resend email verification code. Response Returns status 200 if resent successfully. Status Codes

200 OK: Code resent
409 Conflict: No pending verification or resend not available
429 Too Many Requests: Rate limited

Phone Verification

POST /auth/phone/verify

Verify a phone number with a code. Request Body

string

required

The verification code received via SMS

Response Returns an AuthenticationResponse. Status Codes

200 OK: Phone verified
409 Conflict: No pending phone verification

POST /auth/phone/verify/resend

Resend phone verification code. Response Returns status 200 if resent successfully. Status Codes

429 Too Many Requests: Rate limited

Password Management

POST /auth/password/request

Request a password reset. Request Body

string

required

Email address of the account

Response Returns status 200 regardless of whether the email exists (to prevent user enumeration). Status Codes

200 OK: Reset initiated (if account exists)
429 Too Many Requests: Rate limited

GET /auth/password/reset

Validate a password reset key. Headers

string

required

The reset key from the email link or code

Response Fields

object

User information for the account being reset

Status Codes

200 OK: Reset key is valid
409 Conflict: No pending password reset

Rate Limiting: This endpoint is rate-limited per the reset_password_from_key action.

POST /auth/password/reset

Complete password reset with new password. Request Body

string

required

The reset key (for link-based reset)

string

required

New password

Response Returns an AuthenticationResponse with the user authenticated. Rate Limiting: This endpoint is rate-limited per the reset_password_from_key action.

POST /account/password/change

Change the password for an authenticated user. Request Body

string

Current password (omit if setting password for the first time)

string

required

New password

Response Returns an AuthenticationResponse. Authentication: Required Rate Limiting: This endpoint is rate-limited per the change_password action.

Email Management

GET /account/email

List all email addresses for the current user. Response Returns an array of email address objects.

string

Email address

boolean

Whether the email is verified

boolean

Whether this is the primary email

Example Response

[
  {
    "email": "user@example.com",
    "verified": true,
    "primary": true
  },
  {
    "email": "alternate@example.com",
    "verified": false,
    "primary": false
  }
]

Authentication: Required

POST /account/email

Add a new email address. Request Body

string

required

New email address to add

Response Returns updated list of email addresses. Authentication: Required Rate Limiting: Rate-limited per the manage_email action.

DELETE /account/email

Remove an email address. Request Body

string

required

Email address to remove

Response Returns updated list of email addresses. Authentication: Required Rate Limiting: Rate-limited per the manage_email action.

PATCH /account/email

Mark an email address as primary. Request Body

string

required

Email address to mark as primary

Response Returns updated list of email addresses. Authentication: Required Rate Limiting: Rate-limited per the manage_email action.

PUT /account/email

Resend verification email. Request Body

string

required

Email address to resend verification for

Response Status Codes

200 OK: Verification sent
403 Forbidden: Verification not sent (rate limited or already verified)

Authentication: Required Rate Limiting: Rate-limited per the manage_email action.

Phone Management

GET /account/phone

Get the current phone number. Response Returns an array with the phone number (if set).

string

Phone number in E.164 format

boolean

Whether the phone is verified

Example Response

[
  {
    "phone": "+14155552671",
    "verified": true
  }
]

Authentication: Required

POST /account/phone

Change phone number (initiates verification). Request Body

string

required

New phone number in E.164 format

Response Returns the new phone number with verified: false. Status Codes

202 Accepted: Verification code sent

Authentication: Required Rate Limiting: Rate-limited per the change_phone action. Available when SOCIALACCOUNT_ENABLED is True.

POST /auth/provider/redirect

Initiate OAuth provider redirect flow. Request Body

string

required

Provider ID (e.g., google, github)

string

URL to redirect to after authentication

string

Either login or connect

Response Fields

string

URL to redirect the user to for OAuth authorization

POST /auth/provider/token

Authenticate using provider token (for mobile apps). Request Body

string

required

Provider ID

string

OAuth access token

string

OAuth ID token (for OpenID Connect)

string

OAuth client ID (required for some providers)

Response Returns an AuthenticationResponse.

Complete social account signup. Request Body

string

Email to use (if not provided by OAuth)

Response Returns an AuthenticationResponse.

GET /account/providers

List connected social accounts. Response Returns an array of connected provider accounts. Authentication: Required

MFA Endpoints

Available when MFA_ENABLED is True.

POST /auth/2fa/authenticate

Authenticate with a second factor. Request Body

string

required

TOTP code or recovery code

Response Returns an AuthenticationResponse.

GET /account/authenticators

List configured MFA authenticators. Response Returns an array of authenticator objects. Authentication: Required

GET /account/authenticators/totp

Get TOTP authenticator details or generate new secret. Response Fields

string

TOTP secret (when generating new)

string

Data URL for QR code

Authentication: Required

POST /account/authenticators/totp

Activate TOTP authenticator. Request Body

string

required

TOTP code to verify setup

Response Returns authenticator details. Authentication: Required

Token Endpoints (App Client Only)

Available only for the app client.

POST /tokens/refresh

Refresh an access token using a refresh token. Request Body

string

required

Valid refresh token

Response Fields

string

New access token

string

New refresh token (if rotation is enabled)

Example Request

{
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Example Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Common Response Types

AuthenticationResponse

Returned by most authentication-related endpoints.

object

Response data

Show properties

object

User information (when authenticated)

Show properties

string | number

User ID

string

Display name

string

Primary email address

string

Username (if enabled)

boolean

Whether the account has a password set

array

Authentication methods used in current session

array

Available or pending authentication flows

Show properties

string

Flow identifier

boolean

Whether this flow is currently active

object

Metadata

Show properties

boolean

Whether the user is authenticated

string

Access token (app client with JWT strategy)

string

Refresh token (app client with JWT strategy)

string

Session token (app client)

Example Response (Authenticated)

{
  "data": {
    "user": {
      "id": 123,
      "display": "John Doe",
      "email": "john@example.com",
      "has_usable_password": true
    },
    "methods": [
      {
        "method": "password",
        "at": 1678901234,
        "email": "john@example.com"
      }
    ]
  },
  "meta": {
    "is_authenticated": true,
    "session_token": "abc123..."
  }
}

Example Response (Not Authenticated)

{
  "data": {
    "flows": [
      {"id": "login"},
      {"id": "signup"},
      {"id": "provider_redirect"}
    ]
  },
  "meta": {
    "is_authenticated": false
  }
}

Error Responses

All endpoints may return error responses with validation errors. Error Response Format

{
  "errors": [
    {
      "code": "invalid",
      "param": "email",
      "message": "Enter a valid email address."
    }
  ]
}

Common Error Codes

required: Required field is missing
invalid: Field value is invalid
email_password_mismatch: Invalid email/password combination
username_password_mismatch: Invalid username/password combination
too_many_login_attempts: Login temporarily blocked due to failed attempts

Status Codes

200 OK: Request successful
202 Accepted: Request accepted, pending further action
400 Bad Request: Invalid request data
401 Unauthorized: Authentication required or failed
403 Forbidden: Action not allowed
409 Conflict: Request conflicts with current state
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

​Base URL Structure

​Configuration

​GET /config

​Authentication

​POST /auth/login

​POST /auth/signup

​GET /auth/session

​DELETE /auth/session

​POST /auth/code/request

​POST /auth/code/confirm

​POST /auth/reauthenticate

​Email Verification

​GET /auth/email/verify

​POST /auth/email/verify

​POST /auth/email/verify/resend

​Phone Verification

​POST /auth/phone/verify

​POST /auth/phone/verify/resend

​Password Management

​POST /auth/password/request

​GET /auth/password/reset

​POST /auth/password/reset

​POST /account/password/change

​Email Management

​GET /account/email

​POST /account/email

​DELETE /account/email

​PATCH /account/email

​PUT /account/email

​Phone Management

​GET /account/phone

​POST /account/phone

​Social Account Endpoints

​POST /auth/provider/redirect

​POST /auth/provider/token

​POST /auth/provider/signup

​GET /account/providers

​MFA Endpoints

​POST /auth/2fa/authenticate

​GET /account/authenticators

​GET /account/authenticators/totp

​POST /account/authenticators/totp

​Token Endpoints (App Client Only)

​POST /tokens/refresh

​Common Response Types

​AuthenticationResponse

​Error Responses

​Status Codes

Base URL Structure

Configuration

GET /config

Authentication

POST /auth/login

POST /auth/signup

GET /auth/session

DELETE /auth/session

POST /auth/code/request

POST /auth/code/confirm

POST /auth/reauthenticate

Email Verification

GET /auth/email/verify

POST /auth/email/verify

POST /auth/email/verify/resend

Phone Verification

POST /auth/phone/verify

POST /auth/phone/verify/resend

Password Management

POST /auth/password/request

GET /auth/password/reset

POST /auth/password/reset

POST /account/password/change

Email Management

GET /account/email

POST /account/email

DELETE /account/email

PATCH /account/email

PUT /account/email

Phone Management

GET /account/phone

POST /account/phone

Social Account Endpoints

POST /auth/provider/redirect

POST /auth/provider/token

POST /auth/provider/signup

GET /account/providers

MFA Endpoints

POST /auth/2fa/authenticate

GET /account/authenticators

GET /account/authenticators/totp

POST /account/authenticators/totp

Token Endpoints (App Client Only)

POST /tokens/refresh

Common Response Types

AuthenticationResponse

Error Responses

Status Codes