> ## Documentation Index > Fetch the complete documentation index at: https://mintlify.com/pennersr/django-allauth/llms.txt > Use this file to discover all available pages before exploring further. # Headless API Endpoints > Complete reference for django-allauth headless REST API endpoints 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 configuration settings Available login methods: `email`, `username`, or `phone` Whether new user registration is enabled Whether email verification uses codes instead of links Whether passwordless login via code is enabled Whether password reset uses codes instead of links Legacy field: `email`, `username`, or `username_email` **Example Response** ```json theme={null} { "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** User's email address (when email login is enabled) User's username (when username login is enabled) User's phone number in E.164 format (when phone login is enabled) User's password **Response** Returns an [AuthenticationResponse](#authenticationresponse) with user data and session information. **Example Request** ```json theme={null} { "email": "user@example.com", "password": "secretpassword" } ``` **Rate Limiting**: This endpoint is rate-limited per the `login` action. *** ### POST /auth/signup Register a new user account. **Request Body** User's email address Desired username (if username field is configured) Account password (required unless passwordless signup is configured) **Response** Returns an [AuthenticationResponse](#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](#authenticationresponse) with current user information or 401 if not authenticated. *** ### DELETE /auth/session Log out the current user. **Response** Returns an [AuthenticationResponse](#authenticationresponse) with `is_authenticated: false`. *** ### POST /auth/code/request Request a login code for passwordless authentication. **Request Body** Email address to send the code to Phone number to send the code to (E.164 format) **Response** Returns an [AuthenticationResponse](#authenticationresponse) with a pending `login_by_code` flow. *** ### POST /auth/code/confirm Confirm a login code. **Request Body** The verification code received via email or SMS **Response** Returns an [AuthenticationResponse](#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** User's current password **Response** Returns an [AuthenticationResponse](#authenticationresponse). **Rate Limiting**: This endpoint is rate-limited per the `reauthenticate` action. ## Email Verification ### GET /auth/email/verify Verify an email address. **Headers** The verification key from the email link or code **Response Fields** The email address being verified User information 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** The verification key **Response** Returns an [AuthenticationResponse](#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** The verification code received via SMS **Response** Returns an [AuthenticationResponse](#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 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** The reset key from the email link or code **Response Fields** 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** The reset key (for link-based reset) New password **Response** Returns an [AuthenticationResponse](#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 (omit if setting password for the first time) New password **Response** Returns an [AuthenticationResponse](#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 address Whether the email is verified Whether this is the primary email **Example Response** ```json theme={null} [ { "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** 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 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 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 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 number in E.164 format Whether the phone is verified **Example Response** ```json theme={null} [ { "phone": "+14155552671", "verified": true } ] ``` **Authentication**: Required *** ### POST /account/phone Change phone number (initiates verification). **Request Body** 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 ID (e.g., `google`, `github`) URL to redirect to after authentication Either `login` or `connect` **Response Fields** URL to redirect the user to for OAuth authorization *** ### POST /auth/provider/token Authenticate using provider token (for mobile apps). **Request Body** Provider ID OAuth access token OAuth ID token (for OpenID Connect) OAuth client ID (required for some providers) **Response** Returns an [AuthenticationResponse](#authenticationresponse). *** ### POST /auth/provider/signup Complete social account signup. **Request Body** Email to use (if not provided by OAuth) **Response** Returns an [AuthenticationResponse](#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** TOTP code or recovery code **Response** Returns an [AuthenticationResponse](#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** TOTP secret (when generating new) Data URL for QR code **Authentication**: Required *** ### POST /account/authenticators/totp Activate TOTP authenticator. **Request Body** 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** Valid refresh token **Response Fields** New access token New refresh token (if rotation is enabled) **Example Request** ```json theme={null} { "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` **Example Response** ```json theme={null} { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` ## Common Response Types ### AuthenticationResponse Returned by most authentication-related endpoints. Response data User information (when authenticated) User ID Display name Primary email address Username (if enabled) Whether the account has a password set Authentication methods used in current session Available or pending authentication flows Flow identifier Whether this flow is currently active Metadata Whether the user is authenticated Access token (app client with JWT strategy) Refresh token (app client with JWT strategy) Session token (app client) **Example Response (Authenticated)** ```json theme={null} { "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)** ```json theme={null} { "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** ```json theme={null} { "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