Skip to main content
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
​
account
object
Account configuration settings
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

​
POST /auth/login

Authenticate a user with credentials. Request Body
​
email
string
User’s email address (when email login is enabled)
​
username
string
User’s username (when username login is enabled)
​
phone
string
User’s phone number in E.164 format (when phone login is enabled)
​
password
string
required
User’s password
Response Returns an AuthenticationResponse with user data and session information. Example Request 
{
  "email": "[email protected]",
  "password": "secretpassword"
}
Rate Limiting: This endpoint is rate-limited per the login action.

​
POST /auth/signup

Register a new user account. Request Body
​
email
string
required
User’s email address
​
username
string
Desired username (if username field is configured)
​
password
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
​
email
string
Email address to send the code to
​
phone
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
​
code
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
​
password
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
​
X-Email-Verification-Key
string
required
The verification key from the email link or code
Response Fields
​
email
string
The email address being verified
​
user
object
User information
​
meta.is_authenticating
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
​
key
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
​
code
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
​
email
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
​
X-Password-Reset-Key
string
required
The reset key from the email link or code
Response Fields
​
user
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
​
key
string
required
The reset key (for link-based reset)
​
password
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
​
current_password
string
Current password (omit if setting password for the first time)
​
new_password
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.
​
[].email
string
Email address
​
[].verified
boolean
Whether the email is verified
​
[].primary
boolean
Whether this is the primary email
Example Response 
[
  {
    "email": "[email protected]",
    "verified": true,
    "primary": true
  },
  {
    "email": "[email protected]",
    "verified": false,
    "primary": false
  }
]
Authentication: Required

​
POST /account/email

Add a new email address. Request Body
​
email
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
​
email
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
​
email
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
​
email
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).
​
[].phone
string
Phone number in E.164 format
​
[].verified
boolean
Whether the phone is verified
Example Response 
[
  {
    "phone": "+14155552671",
    "verified": true
  }
]
Authentication: Required

​
POST /account/phone

Change phone number (initiates verification). Request Body
​
phone
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.

​
Social Account Endpoints

Available when SOCIALACCOUNT_ENABLED is True.

​
POST /auth/provider/redirect

Initiate OAuth provider redirect flow. Request Body
​
provider
string
required
Provider ID (e.g., google, github)
​
callback_url
string
URL to redirect to after authentication
​
process
string
Either login or connect
Response Fields
​
redirect_url
string
URL to redirect the user to for OAuth authorization

​
POST /auth/provider/token

Authenticate using provider token (for mobile apps). Request Body
​
provider
string
required
Provider ID
​
access_token
string
OAuth access token
​
id_token
string
OAuth ID token (for OpenID Connect)
​
client_id
string
OAuth client ID (required for some providers)
Response Returns an AuthenticationResponse.

​
POST /auth/provider/signup

Complete social account signup. Request Body
​
email
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
​
code
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
​
secret
string
TOTP secret (when generating new)
​
qr_code_url
string
Data URL for QR code
Authentication: Required

​
POST /account/authenticators/totp

Activate TOTP authenticator. Request Body
​
code
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
​
refresh_token
string
required
Valid refresh token
Response Fields
​
access_token
string
New access token
​
refresh_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.
​
data
object
Response data
​
meta
object
Metadata
Example Response (Authenticated) 
{
  "data": {
    "user": {
      "id": 123,
      "display": "John Doe",
      "email": "[email protected]",
      "has_usable_password": true
    },
    "methods": [
      {
        "method": "password",
        "at": 1678901234,
        "email": "[email protected]"
      }
    ]
  },
  "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

Build docs developers (and LLMs) love

Get started for freeTalk to us