{"openapi": "3.0.3", "info": {"version": "1", "title": "django-allauth: Headless API", "description": "# Introduction\n\nWelcome to the django-allauth API specification. This API is intended to be\nconsumed by two different kind of clients:\n\n- Web applications running in a **browser** context. For example, a\n  single-page React application, to which the end user can navigate using a web\n  browser.\n\n- Applications, **apps** for short, executing in non-browser contexts. For example,\n  a mobile Android or iOS application.\n\nThe security considerations for these two usage types are different. In a\nbrowser context, cookies play a role.  Without taking special precautions, your\nweb application may be vulnerable to Cross-Site Request Forgery attacks.  For\nmobile applications, this does not apply.\n\nThe API can be used for both use cases. Differences in handling of security is\nautomatically adjusted for, based on the request path used to make the API call.\nFor example, signing up can either be done using the\n`/_allauth/browser/v1/auth/signup` or the `/_allauth/app/v1/auth/signup`\nendpoint. For the **browser** usage, session cookies and CSRF protection\napplies. For the **app** usage, cookies play no role, instead, a session token\nis used.  The paths of all endpoints are documented in the form of\n`/_allauth/{client}/v1/auth/signup`. Depending on the client type (`{client}`),\nthere may be slight differences in request/response handling.  This is\ndocumented where applicable.\n\n\n# Scope\n\nThe following functionality is all in scope and handled as part of this API:\n\n- Regular accounts:\n  - Login\n  - Signup\n  - Password forgotten\n  - Manage email (add, remove, verify, select a different primary)\n  - Change password.\n  - Verification of email addresses.\n- Two-Factor Authentication:\n  - Authentication using an authenticator code\n  - (De)activate TOTP\n  - (Re)generate recovery codes\n  - \"Trust this browser\"\n- Third-party providers:\n  - Authenticate by performing a browser-level redirect (synchronous request).\n  - Authenticate by means of a provider token.\n  - Connect additional provider accounts.\n  - Disconnect existing provider accounts.\n  - Setting a password in case no password was set, yet.\n  - Querying additional information before signing up.\n- Session management:\n  - Listing all sessions for a user.\n  - Signing out of any of those sessions.\n\n\n# Browser Usage\n\nFor web applications running in a browser, routing needs to be setup correctly\nsuch that the sessions initiated at the backend are accessible in the frontend.\n\n## Routing\n\nWhen using the API in a browser context, regular Django sessions are used, along\nwith the usual session cookies. There are several options for setting up the\nrouting of your application.\n\n\n###  Single Domain Routing\n\nWith single domain, path-based routing, both your frontend and backend are\nserved from the same domain, for example `https://app.org`. You will have to\nmake sure that some paths are served by the frontend, and others by the backend.\n\n\n### Sub-domain Routing\n\nWith sub-domain based routing, the frontend and backend are served from\ndifferent domains.  However, as session cookies are used, these different\ndomains must share common main domain.\n\nFor example, you may use `app.project.org` for the frontend, which\ninterfaces with the backend over at `backend.project.org`.  In this\nsetup, Django will need to be configured with:\n\n```\nSESSION_COOKIE_DOMAIN = \"project.org\"\nCSRF_COOKIE_DOMAIN = \"project.org\"\n```\n\nIf your organization hosts unrelated applications, for example, a CMS for\nmarketing purposes, on the top level domain (`project.org`), it is not advisable\nto set the session cookie domain to `project.org`, as those other applications\ncould get access to the session cookie. In that case, it is advised to use\n`backend.app.project.org` for the backend, and set the session cookie domain to\n`app.project.org`.\n\n\n# App Usage\n\nFor app based usage, cookies play no role, yet, sessions are still used. When a\nuser walks through the authentication flow, a session is created.  Having an\nauthenticated session is proof that the user is allowed to further interact with\nthe backend. Unauthenticated sessions are also needed to remember state while\nthe user proceeds to go over the required steps necessary to authenticate.\n\n\n## Session Tokens\n\nGiven that there is no cookie to point to the session, the header\n`X-Session-Token` is used instead. The way of working is as follows:\n\n- If you do not have a session token yet, do not send the `X-Session-Token` header.\n\n- When making requests, session tokens can appear in the metadata\n  (`meta.session_token`) of authentication related responses. If a session\n  token appears, store it (overwriting any previous session token), and ensure\n  to add the token to the `X-Session-Token` header of all subsequent requests.\n\n- When receiving an authentication related response with status code 410\n  (`Gone`), that is meant to indicate that the session is no longer valid.\n  Remove the session token and start clean.\n\n\n## Access Tokens\n\nWhile session tokens are required to handle the authentication process,\ndepending on your requirements, a different type of token may be needed once\nauthenticated.\n\nFor example, your app likely needs access to other APIs as well. These APIs may\n even be implemented using different technologies, in which case having a\n stateless token, possibly a JWT encoding the user ID, might be a good fit.\n\nIn this API and its implementation no assumptions, and no (limiting) design\ndecisions are made in this regard. The token strategy of django-allauth is\npluggable, such that you can expose your own access token when the user\nauthenticates. As for as the API specification is concerned, the access token\nwill appear in the response of metadata (`meta.access_token`) of a successful\nauthentication request. How you can customize the token strategy can be found\nover at the documentation of the `allauth.headless` Django application.\n\n\n# Responses\n\nUnless documented otherwise, responses are objects with the following\nproperties:\n- The `status`, matching the HTTP status code.\n- Data, if any, is returned as part of the `data` key.\n- Metadata, if any, is returned as part of the `meta` key.\n- Errors, if any, are listed in the `errors` key.\n\n\n# Authentication Flows\n\nIn order to become authenticated, the user must complete a flow, potentially\nconsisting of several steps. For example:\n- A login, after which the user is authenticated.\n- A Login, followed by two-factor authentication, after which the user is\n  authenticated.\n- A signup, followed by mandatory email verification, after which the user is\n  authenticated.\n\nThe API signals to the client that (re)authentication is required by means of a\n`401` or `410` status code:\n- Not authenticated: status `401`.\n- Re-authentication required: status `401`, with `meta.is_authenticated = true`.\n- Invalid session: status `410`. This only occurs for clients of type `app`.\n\nAll authentication related responses have status `401` or `410`, and,\n`meta.is_authenticated` indicating whether authentication, or re-authentication\nis required.\n\nThe flows the client can perform to initiate or complete the authentication are\ncommunicates as part of authentication related responses. The authentication can\nbe initiated by means of these flows:\n- Login using a local account (`login`).\n- Signup for a local account (`signup`).\n- Login or signup using the third-party provider redirect flow (`provider_redirect`).\n- Login or signup by handing over a third-party provider retrieved elsewhere (`provider_token`).\n- Login using a special code (`login_by_code`).\n- Login using a passkey (`mfa_login_webauthn`).\n- Signup using a passkey (`mfa_signup_webauthn`).\n\nDepending on the state of the account, and the configuration of django-allauth, the flows above\ncan either lead to becoming directly authenticated, or, to followup flows:\n- Provider signup (`provider_signup`).\n- Email verification (`verify_email`).\n- Phone verification (`phone_email`).\n- Two-factor authentication required (TOTP, recovery codes, or WebAuthn) (`mfa_authenticate`).\n- Trust this browser (`mfa_trust`).\n\nWhile authenticated, re-authentication may be required to safeguard the account when sensitive actions\nare performed. The re-authentication flows are the following:\n- Re-authenticate using password (`reauthenticate`).\n- Re-authenticate using a 2FA authenticator (TOTP, recovery codes, or WebAuthn) (`mfa_reauthenticate`).\n\n\n# Security Considerations\n\n## Input Sanitization\n\nThe Django framework, by design, does *not* perform input sanitization. For\nexample, there is nothing preventing end users from signing up using `<script>`\nor `Robert'); DROP TABLE students` as a first name. Django relies on its\ntemplate language for proper escaping of such values and mitigate any XSS\nattacks.\n\nAs a result, any `allauth.headless` client **must** have proper XSS protection\nin place as well. Be prepared that, for example, the WebAuthn endpoints could\nreturn authenticator names as follows:\n\n    {\n      \"name\": \"<script>alert(1)</script>\",\n      \"credential\": {\n        \"type\": \"public-key\",\n        ...\n      }\n    }", "contact": {"email": "info@allauth.org"}, "license": {"name": "MIT", "url": "https://opensource.org/license/mit"}}, "externalDocs": {"description": "The django-allauth project.", "url": "http://allauth.org"}, "tags": [{"name": "Configuration", "description": "Exposes information on the configuration of django-allauth.\n"}, {"name": "Authentication: Account", "description": "All functionality related towards authenticating regular\nusername/email-password based accounts.\n"}, {"name": "Account: Email", "description": "The API used for manipulating the email addresses attached to a given\naccount. This is intentionally modeled as one endpoint, representing the\ncollection of all the email addresses. Note that manipulating one email\naddress may affect another.  For example, marking one email address as\nprimary implies the previous primary email address is changed as\nwell. Also, if django-allauth is configured with `ACCOUNT_CHANGE_EMAIL =\nTrue`, verifying the email address the user is changing to will cause the\nprevious email addres to be removed.\n"}, {"name": "Account: Phone", "description": "The API used for manipulating the phone number attached to a given\naccount.\n"}, {"name": "Account: Password", "description": "Endpoints that can be used to alter the password for a given account.\n"}, {"name": "Account: Providers", "description": "Management of third-party provider accounts that are connected to the\nauthenticated account.\n"}], "x-tagGroups": [{"name": "Overall", "tags": ["Configuration"]}, {"name": "Authentication", "tags": ["Authentication: Current Session", "Authentication: Account", "Authentication: Password Reset", "Authentication: Providers", "Authentication: 2FA", "Authentication: Login By Code", "Authentication: WebAuthn: Login", "Authentication: WebAuthn: Signup"]}, {"name": "Account", "tags": ["Account: Email", "Account: Password", "Account: Phone", "Account: Providers", "Account: 2FA", "Account: WebAuthn"]}, {"name": "Tokens", "tags": ["Tokens"]}], "paths": {"/auth-api/{client}/v1/config": {"get": {"summary": "Get configuration", "tags": ["Configuration"], "description": "There are many configuration options that alter the functionality\nand behavior of django-allauth, some of which can also impact the\nfrontend. Therefore, relevant configuration options are exposed via\nthis endpoint. The data returned is not user/authentication\ndependent. Hence, it suffices to only fetch this data once at boot\ntime of your application.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "responses": {"200": {"$ref": "#/components/responses/Configuration"}}}}, "/auth-api/{client}/v1/auth/login": {"post": {"tags": ["Authentication: Account"], "summary": "Login", "description": "Login using a username-password or email-password combination.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/Login"}, "responses": {"200": {"$ref": "#/components/responses/AuthenticatedByPassword"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmail"}, "password_mismatch": {"$ref": "#/components/examples/PasswordMismatch"}}}}}, "401": {"description": "Not authenticated.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"pending_email": {"$ref": "#/components/examples/UnauthenticatedPendingEmailVerification"}, "pending_2fa": {"$ref": "#/components/examples/UnauthenticatedPending2FA"}}}}}, "409": {"description": "Conflict. For example, when logging in when a user is already logged in.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/signup": {"post": {"tags": ["Authentication: Account"], "summary": "Signup", "description": "Whether or not `username`, `email`, `phone` or combination of those are\nrequired depends on the configuration of django-allauth. Additionally,\nif a custom signup form is used there may be other custom properties\nrequired.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/Signup"}, "responses": {"200": {"$ref": "#/components/responses/AuthenticatedByPassword"}, "400": {"description": "An input error occurred.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "401": {"description": "Not authenticated.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"pending_email": {"$ref": "#/components/examples/UnauthenticatedPendingEmailVerification"}}}}}, "403": {"description": "Forbidden. For example, when signup is closed.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ForbiddenResponse"}}}}, "409": {"description": "Conflict. For example, when signing up while user is logged in.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/email/verify": {"get": {"tags": ["Authentication: Account"], "summary": "Get email verification information", "description": "Obtain email verification information, given the token that was sent to\nthe user by email.\n", "parameters": [{"$ref": "#/components/parameters/EmailVerificationKey"}, {"$ref": "#/components/parameters/Client"}], "responses": {"200": {"$ref": "#/components/responses/EmailVerificationInfo"}, "400": {"description": "An input error occurred.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmailVerificationKey"}}}}}, "409": {"description": "Conflict. The email verification (by code) flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}, "post": {"tags": ["Authentication: Account"], "summary": "Verify an email", "description": "Complete the email verification process. Depending on the configuration,\nemail addresses are either verified by opening a link that is sent to\ntheir email address, or, by inputting a code that is sent. On the API,\nboth cases are handled identically. Meaning, the required key is either\nthe one from the link, or, the code itself.\n\nNote that a status code of 401 does not imply failure. It indicates that\nthe email verification was successful, yet, the user is still not signed\nin. For example, in case `ACCOUNT_LOGIN_ON_EMAIL_CONFIRMATION` is set to\n`False`, a 401 is returned when verifying as part of login/signup.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/VerifyEmail"}, "responses": {"200": {"$ref": "#/components/responses/Authenticated"}, "400": {"description": "An input error occurred.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmailVerificationKey"}}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "409": {"description": "Conflict. The email verification (by code) flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/email/verify/resend": {"post": {"tags": ["Authentication: Account"], "summary": "Resend email verification code", "description": "Requests a new email verification code.\nRequires `ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_RESEND = True`.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/StatusOK"}, "409": {"description": "Conflict. The email verification (by code) flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}, "429": {"$ref": "#/components/responses/TooManyRequests"}}}}, "/auth-api/{client}/v1/auth/phone/verify": {"post": {"tags": ["Authentication: Account"], "summary": "Verify a phone number", "description": "Complete the phone number verification process. Note that a status code\nof 401 does not imply failure. It merely indicates that the phone number\nverification was successful, yet, the user is still not signed in.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/VerifyPhone"}, "responses": {"200": {"$ref": "#/components/responses/Authenticated"}, "400": {"description": "An input error occurred.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "401": {"$ref": "#/components/responses/Unauthenticated"}, "409": {"description": "Conflict. The phone verification flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/phone/verify/resend": {"post": {"tags": ["Authentication: Account"], "summary": "Resend phone number verification code", "description": "Requests a new phone number verification code.\nRequires `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_RESEND = True`.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/StatusOK"}, "409": {"description": "Conflict. The phone verification flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}, "429": {"$ref": "#/components/responses/TooManyRequests"}}}}, "/auth-api/{client}/v1/auth/reauthenticate": {"post": {"tags": ["Authentication: Account"], "summary": "Reauthenticate", "description": "In order to safeguard the account, some actions require the user to be\nrecently authenticated.  If you try to perform such an action without\nhaving been recently authenticated, a `401` status is returned, listing\nflows that can be performed to reauthenticate. One such flow is the flow\nwith ID `reauthenticate`, which allows for the user to input the\npassword. This is the endpoint related towards that flow.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/Reauthenticate"}, "responses": {"200": {"$ref": "#/components/responses/AuthenticatedByPassword"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/IncorrectPassword"}}}}}}}}, "/auth-api/{client}/v1/auth/password/request": {"post": {"summary": "Request password", "description": "Initiates the password reset procedure. Depending on whether or not\n`ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED` is `True`, the procedure is\neither stateless or stateful.\n\nIn case codes are used, it is stateful, and a new\n`password_reset_by_code` flow is started. In this case, on a successful\npassword reset request, you will receive a 401 indicating the pending\nstatus of this flow.\n\nIn case password reset is configured to use (stateless) links, you will\nreceive a 200 on a successful password reset request.\n", "tags": ["Authentication: Password Reset"], "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/RequestPassword"}, "responses": {"200": {"$ref": "#/components/responses/StatusOK"}, "400": {"description": "An input error occurred.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "401": {"$ref": "#/components/responses/Authentication"}}}}, "/auth-api/{client}/v1/auth/password/reset": {"get": {"summary": "Get password reset information", "description": "Used to obtain information on and validate a password reset key.  The\nkey passed is either the key encoded in the password reset URL that the\nuser has received per email, or, the password reset code in case of\n`ACCOUNT_PASSWORD_RESET_BY_CODE_ENABLED`. Note that in case of a code,\nthe number of requests you can make is limited (by\n`ACCOUNT_PASSWORD_RESET_BY_CODE_MAX_ATTEMPTS`).\n", "tags": ["Authentication: Password Reset"], "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/PasswordResetKey"}], "responses": {"200": {"$ref": "#/components/responses/PasswordResetInfo"}, "400": {"description": "An input error occurred.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"password_reset_key_invalid": {"$ref": "#/components/examples/InvalidPasswordResetKey"}}}}}, "409": {"description": "Conflict. There is no password reset (by code) flow pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}, "post": {"summary": "Reset password", "description": "Perform the password reset, by handing over the password reset key and\nthe new password. After successfully completing the password reset, the\nuser is either logged in (in case `ACCOUNT_LOGIN_ON_PASSWORD_RESET` is\n`True`), or, the user will need to proceed to the login page.  In case\nof the former, a `200` status code is returned, in case of the latter a\n401.\n", "tags": ["Authentication: Password Reset"], "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/ResetPassword"}, "responses": {"200": {"$ref": "#/components/responses/AuthenticatedByPassword"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "401": {"$ref": "#/components/responses/Authentication"}, "409": {"description": "Conflict. There is no password reset (by code) flow pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/browser/v1/auth/provider/redirect": {"post": {"tags": ["Authentication: Providers"], "summary": "Provider redirect", "description": "Initiates the third-party provider authentication redirect flow. As calling\nthis endpoint results in a user facing redirect (302), this call is only\navailable in a browser, and must be called in a synchronous (non-XHR)\nmanner.\n", "requestBody": {"$ref": "#/components/requestBodies/ProviderRedirect"}, "responses": {"302": {"description": "The provider authorization URL to which the client should be redirected.", "headers": {"location": {"schema": {"type": "string"}, "description": "The redirect URL."}}}}}}, "/auth-api/{client}/v1/auth/provider/token": {"post": {"tags": ["Authentication: Providers"], "summary": "Provider token", "description": "Authenticates with a third-party provider using provider tokens received\nby other means. For example, in case of a mobile app, the authentication\nflow runs completely on the device itself, without any interaction with\nthe API. Then, when the (device) authentication completes and the mobile\napp receives an access and/or ID token, it can hand over these tokens\nvia this endpoint to authenticate on the server.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/ProviderToken"}, "responses": {"200": {"$ref": "#/components/responses/Authenticated"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_token": {"$ref": "#/components/examples/InvalidProviderToken"}}}}}, "401": {"description": "Not authenticated, more steps are required to be completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"unauthenticated_pending_2fa": {"$ref": "#/components/examples/UnauthenticatedPending2FA"}, "unauthenticated_pending_email_verification": {"$ref": "#/components/examples/UnauthenticatedPendingEmailVerification"}}}}}, "403": {"description": "Forbidden. For example, when signup is closed.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ForbiddenResponse"}}}}}}}, "/auth-api/{client}/v1/auth/provider/signup": {"get": {"tags": ["Authentication: Providers"], "summary": "Provider signup information", "description": "If, while signing up using a third-party provider account, there is\ninsufficient information received from the provider to automatically\ncomplete the signup process, an additional step is needed to complete\nthe missing data before the user is fully signed up and authenticated.\nThe information available so far, such as the pending provider account,\ncan be retrieved via this endpoint.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "responses": {"200": {"$ref": "#/components/responses/ProviderSignup"}, "409": {"description": "Conflict. The provider signup flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}, "post": {"tags": ["Authentication: Providers"], "summary": "Provider signup", "description": "If, while signing up using a third-party provider account, there is\ninsufficient information received from the provider to automatically\ncomplete the signup process, an additional step is needed to complete\nthe missing data before the user is fully signed up and authenticated.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/ProviderSignup"}, "responses": {"200": {"$ref": "#/components/responses/Authenticated"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "401": {"description": "Not authenticated, more steps are required to be completed.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"unauthenticated_pending_email_verification": {"$ref": "#/components/examples/UnauthenticatedPendingEmailVerification"}}}}}, "403": {"description": "Forbidden. For example, when signup is closed.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ForbiddenResponse"}}}}, "409": {"description": "Conflict. The provider signup flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/code/request": {"post": {"tags": ["Authentication: Login By Code"], "summary": "Request login code", "description": "Request a \"special\" login code that is sent to the user by email.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/RequestLoginCode"}, "responses": {"400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_email": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "401": {"description": "Not authenticated.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"pending_login_by_code": {"$ref": "#/components/examples/UnauthenticatedPendingLoginByCode"}}}}}}}}, "/auth-api/{client}/v1/auth/code/confirm": {"post": {"tags": ["Authentication: Login By Code"], "summary": "Confirm login code", "description": "Use this endpoint to pass along the received \"special\" login code.\n", "parameters": [{"$ref": "#/components/parameters/Client"}], "requestBody": {"$ref": "#/components/requestBodies/ConfirmLoginCode"}, "responses": {"200": {"$ref": "#/components/responses/AuthenticatedByCode"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_code": {"$ref": "#/components/examples/InvalidAuthenticatorCode"}}}}}, "401": {"description": "Not authenticated.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"unauthenticated_pending_2fa": {"$ref": "#/components/examples/UnauthenticatedPending2FA"}}}}}, "409": {"description": "Conflict. The \"login by code\" flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/code/resend": {"post": {"tags": ["Authentication: Login By Code"], "summary": "Resend login code", "description": "Requests a new login code.\nRequires `ACCOUNT_LOGIN_BY_CODE_SUPPORTS_RESEND = True`.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/StatusOK"}, "409": {"description": "Conflict. The login verification (by code) flow is not pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}, "429": {"$ref": "#/components/responses/TooManyRequests"}}}}, "/auth-api/{client}/v1/account/providers": {"get": {"tags": ["Account: Providers"], "summary": "List the connected third-party provider accounts", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/ProviderAccounts"}}}, "delete": {"tags": ["Account: Providers"], "summary": "Disconnect a third-party provider account\n", "description": "Disconnect a third-party provider account, returning the remaining\naccounts that are still connected. The disconnect is not allowed if it\nwould leave the account unusable. For example, if no password was\nset up yet.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/ProviderAccount"}, "responses": {"200": {"$ref": "#/components/responses/ProviderAccounts"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"no_password": {"$ref": "#/components/examples/DisconnectNotAllowedNoPassword"}, "no_email": {"$ref": "#/components/examples/DisconnectNotAllowedNoVerifiedEmail"}}}}}}}}, "/auth-api/{client}/v1/account/email": {"get": {"tags": ["Account: Email"], "summary": "List email addresses", "description": "Retrieves the list of email addresses of the account.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/EmailAddresses"}, "401": {"$ref": "#/components/responses/Authentication"}}}, "post": {"tags": ["Account: Email"], "summary": "Add/Change email address\n", "description": "The following functionality is available:\n\n  - Adding a new email address for an already signed in user (`ACCOUNT_CHANGE_EMAIL = False`).\n  - Change to a new email address for an already signed in user   (`ACCOUNT_CHANGE_EMAIL = True`).\n  - Change to a new email address during the email verification process at signup (`ACCOUNT_EMAIL_VERIFICATION_SUPPORTS_CHANGE = True`).\n\nIn all cases, an email verification mail will be sent containing a link or code that needs to be verified.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/Email"}, "responses": {"200": {"$ref": "#/components/responses/EmailAddresses"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_code": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "401": {"$ref": "#/components/responses/AuthenticationOrReauthentication"}, "409": {"description": "Conflict. For example, when no user is authenticated and no email verification flow is pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}, "put": {"tags": ["Account: Email"], "summary": "Request email verification", "description": "Requests for (another) email verification email to be sent. Note that\nsending emails is rate limited, so when you send too many requests the\nemail will not be sent.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/Email"}, "responses": {"200": {"$ref": "#/components/responses/StatusOK"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_code": {"$ref": "#/components/examples/InvalidEmail"}}}}}, "403": {"description": "Too many email verification mails were already sent.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ForbiddenResponse"}}}}}}, "patch": {"tags": ["Account: Email"], "summary": "Change primary email address", "description": "Used to change primary email address to a different one. Note that only verified email addresses\ncan be marked as primary.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/MarkPrimaryEmail"}, "responses": {"200": {"$ref": "#/components/responses/EmailAddresses"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_code": {"$ref": "#/components/examples/InvalidEmail"}}}}}}}, "delete": {"tags": ["Account: Email"], "summary": "Remove an email address", "description": "Used to remove an email address.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/Email"}, "responses": {"200": {"$ref": "#/components/responses/EmailAddresses"}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}, "examples": {"invalid_code": {"$ref": "#/components/examples/InvalidEmail"}}}}}}}}, "/auth-api/{client}/v1/account/phone": {"get": {"tags": ["Account: Phone"], "summary": "Get the phone number", "description": "Retrieves the phone number of the account, if any. Note that while the\nendpoint returns a list of phone numbers, at most one entry is returned.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/PhoneNumbers"}, "401": {"$ref": "#/components/responses/Authentication"}}}, "post": {"tags": ["Account: Phone"], "summary": "Change the phone number\n", "description": "The following functionality is available:\n\n- Initiate the phone number change process for signed in users.\n- Change to a new phone number during the phone number verification\n  process at signup for unauthenticated users. Note that this requires:\n  `ACCOUNT_PHONE_VERIFICATION_SUPPORTS_CHANGE = True`.\n\nIn both cases, after posting a new phone number, proceed with the phone\nverification endpoint to confirm the change of the phone number by\nposting the verification code.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/Phone"}, "responses": {"202": {"description": "Phone number change process initiated.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PhoneNumberChangeResponse"}}}}, "400": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "401": {"$ref": "#/components/responses/AuthenticationOrReauthentication"}, "409": {"description": "Conflict. For example, when no user is authenticated and no phone verification flow is pending.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}}}}, "/auth-api/{client}/v1/auth/session": {"get": {"tags": ["Authentication: Current Session"], "summary": "Get authentication status\n", "description": "Retrieve information about the authentication status for the current\nsession.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"200": {"$ref": "#/components/responses/Authenticated"}, "401": {"$ref": "#/components/responses/Authentication"}, "410": {"$ref": "#/components/responses/SessionGone"}}}, "delete": {"tags": ["Authentication: Current Session"], "summary": "Logout", "description": "Logs out the user from the current session.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "responses": {"401": {"$ref": "#/components/responses/Unauthenticated"}}}}, "/auth-api/app/v1/tokens/refresh": {"post": {"tags": ["Tokens"], "summary": "Refresh the access token\n", "description": "Used to retrieve a new access token. Depending on `settings.HEADLESS_JWT_ROTATE_REFRESH_TOKEN`,\na new refresh token is returned as well.\n", "requestBody": {"$ref": "#/components/requestBodies/RefreshToken"}, "responses": {"200": {"$ref": "#/components/responses/RefreshToken"}, "400": {"description": "The refresh token is invalid or expired.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}}}}, "/auth-api/{client}/v1/account/password/change": {"post": {"tags": ["Account: Password"], "summary": "Change password", "description": "In order to change the password of an account, the current and new\npassword must be provider.  However, accounts that were created by\nsigning up using a third-party provider do not have a password set. In\nthat case, the current password is not required.\n", "parameters": [{"$ref": "#/components/parameters/Client"}, {"$ref": "#/components/parameters/SessionToken"}], "requestBody": {"$ref": "#/components/requestBodies/ChangePassword"}, "responses": {"400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Authentication"}}}}}, "components": {"examples": {"User": {"value": {"id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard"}}, "AuthenticatedByPassword": {"summary": "Authenticated by password.\n", "value": {"status": 200, "data": {"user": {"id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard"}, "methods": [{"method": "password", "at": 1711555057.065702, "email": "email@domain.org"}]}, "meta": {"is_authenticated": true, "session_token": "ufwcig0zen9skyd545jc0fkq813ghar2", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW"}}}, "AuthenticatedByCode": {"summary": "Authenticated by code.\n", "value": {"status": 200, "data": {"user": {"id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard"}, "methods": [{"method": "code", "at": 1711555057.065702, "email": "email@domain.org"}]}, "meta": {"is_authenticated": true, "session_token": "ufwcig0zen9skyd545jc0fkq813ghar2", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW"}}}, "AuthenticatedByPasswordAnd2FA": {"summary": "Fully authenticated using by password and 2FA.\n", "value": {"status": 200, "data": {"user": {"id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard"}, "methods": [{"method": "password", "at": 1711555057.065702, "email": "email@domain.org"}, {"method": "mfa", "at": 1711555060.9375854, "id": 66, "type": "totp"}]}, "meta": {"is_authenticated": true, "session_token": "ufwcig0zen9skyd545jc0fkq813ghar2", "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW"}}}, "CannotGenerateRecoveryCodes": {"summary": "Unable to generate recovery codes.\n", "value": {"status": 400, "errors": [{"message": "You cannot deactivate two-factor authentication.\ncode: cannot_generate_recovery_codes\n"}]}}, "DisconnectNotAllowedNoPassword": {"summary": "Account without a password.", "value": {"status": 400, "errors": [{"message": "Your account has no password set up.", "code": "no_password", "param": "account"}]}}, "DisconnectNotAllowedNoVerifiedEmail": {"summary": "Account without a verified email.", "value": {"status": 400, "errors": [{"message": "Your account has no verified email address.", "code": "no_verified_email", "param": "account"}]}}, "InvalidAuthenticatorCode": {"summary": "An error response indicating that the provided code is incorrect.\n", "value": {"status": 400, "errors": [{"message": "Incorrect code.", "code": "incorrect_code", "param": "code"}]}}, "InvalidEmailVerificationKey": {"summary": "Email verification key invalid.\n", "value": {"status": 400, "errors": [{"message": "Invalid or expired key.", "code": "invalid", "param": "key"}]}}, "InvalidEmail": {"value": {"status": 400, "errors": [{"message": "Enter a valid email address.", "code": "invalid", "param": "email"}]}}, "IncorrectPassword": {"value": {"status": 400, "errors": [{"message": "Incorrect password.", "param": "password", "code": "incorrect_password"}]}}, "InvalidPasswordResetKey": {"summary": "Password reset key invalid.\n", "value": {"status": 400, "errors": [{"message": "The password reset token was invalid.", "code": "token_invalid", "param": "key"}]}}, "InvalidProviderToken": {"summary": "Provider token invalid.\n", "value": {"status": 400, "errors": [{"message": "The token was invalid.", "code": "invalid", "param": "token"}]}}, "PasswordMismatch": {"value": {"status": 400, "errors": [{"message": "The email address and/or password you specified are not correct.", "code": "email_password_mismatch", "param": "password"}]}}, "UnauthenticatedInitial": {"summary": "Unauthenticated: Initial\n", "value": {"status": 401, "data": {"flows": [{"id": "login"}, {"id": "signup"}, {"id": "provider_redirect", "providers": ["facebook", "google", "telegram"]}, {"id": "provider_token", "providers": ["google"]}]}, "meta": {"is_authenticated": false}}}, "UnauthenticatedPending2FA": {"summary": "Unauthenticated: pending 2FA\n", "value": {"status": 401, "data": {"flows": [{"id": "login"}, {"id": "signup"}, {"id": "provider_redirect", "providers": ["facebook", "google", "telegram"]}, {"id": "provider_token", "providers": ["google"]}, {"id": "mfa_authenticate", "is_pending": true}]}, "meta": {"is_authenticated": false}}}, "UnauthenticatedPendingLoginByCode": {"summary": "Unauthenticated: pending login by code\n", "value": {"status": 401, "data": {"flows": [{"id": "login"}, {"id": "signup"}, {"id": "provider_redirect", "providers": ["facebook", "google", "telegram"]}, {"id": "provider_token", "providers": ["google"]}, {"id": "mfa_authenticate"}, {"id": "login_by_code", "is_pending": true}]}, "meta": {"is_authenticated": false}}}, "UnauthenticatedPendingProviderSignup": {"summary": "Unauthenticated: pending provider signup\n", "value": {"status": 401, "data": {"flows": [{"id": "login"}, {"id": "signup"}, {"id": "provider_redirect", "providers": ["facebook", "google", "telegram"]}, {"id": "provider_token", "providers": ["google"]}, {"id": "provider_signup", "provider": {"id": "google", "name": "Google", "client_id": "123.apps.googleusercontent.com", "flows": ["provider_redirect", "provider_token"]}, "is_pending": true}]}, "meta": {"is_authenticated": false}}}, "UnauthenticatedPendingEmailVerification": {"summary": "Unauthenticated: pending email verification\n", "value": {"status": 401, "data": {"flows": [{"id": "login"}, {"id": "signup"}, {"id": "provider_redirect", "providers": ["facebook", "google", "telegram"]}, {"id": "provider_token", "providers": ["google"]}, {"id": "verify_email", "is_pending": true}]}, "meta": {"is_authenticated": false}}}, "ReauthenticationRequired": {"summary": "Reauthentication required\n", "value": {"status": 401, "data": {"user": {"id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard"}, "methods": [{"method": "password", "at": 1711555057.065702, "email": "email@domain.org"}, {"method": "mfa", "at": 1711555060.9375854, "id": 66, "type": "totp"}], "flows": [{"id": "reauthenticate"}, {"id": "mfa_reauthenticate"}]}, "meta": {"is_authenticated": true}}}}, "requestBodies": {"Login": {"description": "Login.", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Login"}}}}, "LoginWebAuthn": {"description": "Login using WebAuthn.", "required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"credential": {"$ref": "#/components/schemas/WebAuthnCredential"}}, "required": ["credential"]}}}}, "ReauthenticateWebAuthn": {"description": "Reauthenticate using WebAuthn.", "required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"credential": {"$ref": "#/components/schemas/WebAuthnCredential"}}, "required": ["credential"]}}}}, "AuthenticateWebAuthn": {"description": "Authenticate using WebAuthn.", "required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"credential": {"$ref": "#/components/schemas/WebAuthnCredential"}}, "required": ["credential"]}}}}, "MFAAuthenticate": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MFAAuthenticate"}}}}, "MFATrust": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MFATrust"}}}}, "ConfirmLoginCode": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConfirmLoginCode"}}}}, "EndSessions": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EndSessions"}}}}, "PasskeySignup": {"description": "Signup using a passkey", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PasskeySignup"}}}}, "ProviderAccount": {"content": {"application/json": {"schema": {"type": "object", "properties": {"provider": {"$ref": "#/components/schemas/ProviderID"}, "account": {"$ref": "#/components/schemas/ProviderAccountID"}}, "required": ["account", "provider"]}}}}, "ProviderRedirect": {"required": true, "description": "Initiate the provider redirect flow.\n", "content": {"application/x-www-form-urlencoded": {"schema": {"$ref": "#/components/schemas/ProviderRedirect"}}}}, "ProviderSignup": {"description": "Provider signup.", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderSignup"}}}}, "ProviderToken": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ProviderToken"}}}}, "Reauthenticate": {"description": "Reauthenticate.", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Reauthenticate"}}}}, "RefreshToken": {"content": {"application/json": {"schema": {"type": "object", "properties": {"refresh_token": {"$ref": "#/components/schemas/RefreshToken"}}, "required": ["refresh_token"]}}}}, "RequestPassword": {"description": "Request password.", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RequestPassword"}}}}, "RequestLoginCode": {"description": "Request a login code.", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/RequestLoginCode"}}}}, "SetupTOTP": {"content": {"application/json": {"schema": {"type": "object", "properties": {"code": {"$ref": "#/components/schemas/AuthenticatorCode"}}, "required": ["code"]}}}}, "Signup": {"description": "Signup", "required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Signup"}}}}, "ChangePassword": {"content": {"application/json": {"schema": {"type": "object", "properties": {"current_password": {"$ref": "#/components/schemas/Password"}, "new_password": {"type": "string", "description": "The current password.\n", "example": "Aberto!"}}, "required": ["new_password"]}}}}, "Email": {"content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"$ref": "#/components/schemas/Email"}}, "required": ["email"]}}}}, "MarkPrimaryEmail": {"content": {"application/json": {"schema": {"type": "object", "properties": {"email": {"type": "string", "description": "An email address.\n", "example": "email@domain.org"}, "primary": {"type": "boolean", "enum": [true], "description": "Primary flag.\n"}}, "required": ["email", "primary"]}}}}, "Phone": {"content": {"application/json": {"schema": {"type": "object", "properties": {"phone": {"type": "string", "example": "+314159265359"}}, "required": ["phone"]}}}}, "ResetPassword": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/ResetPassword"}}}}, "VerifyEmail": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifyEmail"}}}}, "VerifyPhone": {"content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifyPhone"}}}}, "UpdateWebAuthn": {"content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"$ref": "#/components/schemas/AuthenticatorID"}, "name": {"type": "string", "example": "Master key"}}}}}}, "AddWebAuthnAuthenticator": {"content": {"application/json": {"schema": {"type": "object", "properties": {"name": {"type": "string", "example": "Master key"}, "credential": {"$ref": "#/components/schemas/WebAuthnCredential"}}, "required": ["credential"]}}}}, "DeleteWebAuthn": {"content": {"application/json": {"schema": {"type": "object", "properties": {"authenticators": {"description": "The IDs of the authenticator that are to be deleted.\n", "type": "array", "items": {"$ref": "#/components/schemas/AuthenticatorID"}}}, "required": ["authenticators"]}}}}}, "schemas": {"Session": {"type": "object", "properties": {"user_agent": {"type": "string", "example": "Mozilla Firefox"}, "ip": {"type": "string", "example": "127.2.3.192"}, "created_at": {"$ref": "#/components/schemas/Timestamp"}, "is_current": {"type": "boolean"}, "id": {"type": "integer", "example": 123}, "last_seen_at": {"$ref": "#/components/schemas/Timestamp"}}, "required": ["user_agent", "ip", "created_at", "is_current", "id"]}, "AccountConfiguration": {"type": "object", "description": "Configuration of the Django `allauth.account` app.\n", "properties": {"login_methods": {"type": "array", "items": {"type": "string", "enum": ["email", "username"]}}, "is_open_for_signup": {"type": "boolean"}, "email_verification_by_code_enabled": {"type": "boolean"}, "login_by_code_enabled": {"type": "boolean"}, "password_reset_by_code_enabled": {"type": "boolean"}}, "required": ["authentication_method", "email_verification_by_code_enabled", "is_open_for_signup", "login_by_code_enabled"]}, "AuthenticationResponse": {"type": "object", "description": "An authentication related response.\n", "properties": {"status": {"type": "integer", "enum": [401]}, "data": {"type": "object", "properties": {"flows": {"type": "array", "items": {"$ref": "#/components/schemas/Flow"}}}, "required": ["flows"]}, "meta": {"$ref": "#/components/schemas/AuthenticationMeta"}}, "required": ["status", "data", "meta"]}, "ForbiddenResponse": {"type": "object", "properties": {"status": {"type": "integer", "enum": [403]}}, "required": ["status"]}, "ConflictResponse": {"type": "object", "properties": {"status": {"type": "integer", "enum": [409]}}, "required": ["status"]}, "EndSessions": {"type": "object", "properties": {"sessions": {"description": "The IDs of the sessions that are to be ended.\n", "type": "array", "items": {"type": "integer", "example": 123}}}, "required": ["sessions"]}, "PhoneNumber": {"type": "object", "description": "A phone number.\n", "properties": {"phone": {"type": "string", "example": "+314159265359"}, "verified": {"type": "boolean"}}, "required": ["phone", "verified"]}, "PhoneNumbersResponse": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/PhoneNumber"}}}, "required": ["status", "data"]}, "PhoneNumberChangeResponse": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusAccepted"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/PhoneNumber"}}}, "required": ["status", "data"], "example": {"status": 202, "data": [{"phone": "+314159265359", "verified": false}]}}, "ReauthenticationResponse": {"type": "object", "description": "A response indicating reauthentication is required.\n", "properties": {"status": {"type": "integer", "enum": [401]}, "data": {"$ref": "#/components/schemas/ReauthenticationRequired"}, "meta": {"$ref": "#/components/schemas/AuthenticatedMeta"}}, "required": ["status", "data", "meta"]}, "SessionGoneResponse": {"type": "object", "description": "The session is expired or invalid.\n", "properties": {"status": {"type": "integer", "enum": [410]}, "data": {"type": "object"}, "meta": {"$ref": "#/components/schemas/AuthenticationMeta"}}, "required": ["status", "data", "meta"]}, "BaseAuthenticationMeta": {"type": "object", "properties": {"session_token": {"type": "string", "description": "The session token (`app` clients only).\n", "example": "ufwcig0zen9skyd545jc0fkq813ghar2"}, "access_token": {"type": "string", "description": "The access token (`app` clients only).\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW"}}}, "AuthenticationMeta": {"allOf": [{"$ref": "#/components/schemas/BaseAuthenticationMeta"}, {"type": "object", "description": "Metadata available in an authentication related response.\n", "properties": {"is_authenticated": {"type": "boolean"}}, "required": ["is_authenticated"]}]}, "AuthenticatedMeta": {"allOf": [{"$ref": "#/components/schemas/BaseAuthenticationMeta"}, {"type": "object", "description": "Metadata available in an re-authentication related response.\n", "properties": {"is_authenticated": {"type": "boolean", "enum": [true]}}, "required": ["is_authenticated"]}]}, "Flow": {"type": "object", "properties": {"id": {"type": "string", "enum": ["login", "login_by_code", "mfa_authenticate", "mfa_reauthenticate", "provider_redirect", "provider_signup", "provider_token", "reauthenticate", "signup", "verify_email", "verify_phone"]}, "provider": {"$ref": "#/components/schemas/Provider"}, "is_pending": {"type": "boolean", "enum": [true]}, "types": {"type": "array", "description": "Matches `settings.MFA_SUPPORTED_TYPES`.", "items": {"$ref": "#/components/schemas/AuthenticatorType"}}}, "required": ["id"]}, "Authenticated": {"type": "object", "properties": {"user": {"$ref": "#/components/schemas/User"}, "methods": {"type": "array", "description": "A list of methods used to authenticate.\n", "items": {"$ref": "#/components/schemas/AuthenticationMethod"}}}, "required": ["user", "methods"]}, "ReauthenticationRequired": {"properties": {"flows": {"type": "array", "items": {"$ref": "#/components/schemas/Flow"}}, "user": {"$ref": "#/components/schemas/User"}, "methods": {"type": "array", "description": "A list of methods used to authenticate.\n", "items": {"$ref": "#/components/schemas/AuthenticationMethod"}}}, "required": ["flows", "user", "methods"], "type": "object"}, "AuthenticationMethod": {"oneOf": [{"type": "object", "title": "Authenticated by username/email login\n", "properties": {"method": {"type": "string", "enum": ["password"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "email": {"$ref": "#/components/schemas/Email"}, "username": {"$ref": "#/components/schemas/Username"}}, "required": ["method", "at"]}, {"type": "object", "title": "Authenticated after password reset\n", "properties": {"method": {"type": "string", "enum": ["password_reset"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "email": {"$ref": "#/components/schemas/Email"}}, "required": ["at", "email", "method"]}, {"type": "object", "title": "Authenticated by confirming a code sent by email.\n", "properties": {"method": {"type": "string", "enum": ["code"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "email": {"$ref": "#/components/schemas/Email"}}, "required": ["at", "email", "method"]}, {"type": "object", "title": "Authenticated by confirming a code sent by phone.\n", "properties": {"method": {"type": "string", "enum": ["code"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "phone": {"$ref": "#/components/schemas/Phone"}}, "required": ["at", "method", "phone"]}, {"type": "object", "title": "Reauthenticated by password\n", "properties": {"method": {"type": "string", "enum": ["password"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "reauthenticated": {"type": "boolean", "enum": [true]}}, "required": ["method", "reauthenticated", "at"]}, {"type": "object", "title": "Authenticated by third-party provider\n", "properties": {"method": {"type": "string", "enum": ["socialaccount"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "provider": {"$ref": "#/components/schemas/ProviderID"}, "uid": {"$ref": "#/components/schemas/ProviderAccountID"}}, "required": ["method", "reauthenticated", "at", "provider", "uid"]}, {"type": "object", "title": "(Re)authenticated by 2FA\n", "properties": {"method": {"type": "string", "enum": ["mfa"]}, "at": {"$ref": "#/components/schemas/Timestamp"}, "type": {"$ref": "#/components/schemas/AuthenticatorType"}, "reauthenticated": {"type": "boolean"}}, "required": ["method", "at", "type"]}]}, "AuthenticatedResponse": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/Authenticated"}, "meta": {"$ref": "#/components/schemas/AuthenticationMeta"}}, "required": ["status", "data", "meta"]}, "MFAAuthenticate": {"type": "object", "properties": {"code": {"$ref": "#/components/schemas/AuthenticatorCode"}}, "required": ["code"]}, "MFATrust": {"type": "object", "properties": {"trust": {"type": "boolean"}}, "required": ["trust"]}, "ConfirmLoginCode": {"type": "object", "properties": {"code": {"$ref": "#/components/schemas/Code"}}, "required": ["code"]}, "ClientID": {"type": "string", "description": "The client ID (in case of OAuth2 or OpenID Connect based providers)\n", "example": "123.apps.googleusercontent.com"}, "ProviderToken": {"type": "object", "properties": {"provider": {"$ref": "#/components/schemas/ProviderID"}, "process": {"$ref": "#/components/schemas/Process"}, "token": {"description": "The token.\n", "type": "object", "properties": {"client_id": {"$ref": "#/components/schemas/ClientID"}, "id_token": {"type": "string", "description": "The ID token.\n", "example": "eyJhbGciOiJI"}, "access_token": {"type": "string", "description": "The access token.\n", "example": "36POk6yJV_adQs"}}, "required": ["client_id"]}}, "required": ["provider", "process", "token"]}, "ProviderRedirect": {"type": "object", "properties": {"provider": {"$ref": "#/components/schemas/ProviderID"}, "callback_url": {"type": "string", "description": "The URL to return to after the redirect flow is complete.\n\nNote that this is not to be mistaken with the callback URL that you\nconfigure over at the OAuth provider during the OAuth app/client\nsetup. The flow is as follows:\n\n  1. Your frontend redirects to the headless provider redirect\n     endpoint in a synchronous (non-XHR) manner, informing allauth\n     (by means of `callback_url`) where to redirect to after the\n     provider handshake is completed.\n\n  2. Headless will redirect to the (OAuth) identity provider to\n     initiate the handshake, passing along a different callback URL\n     to the provider: one that points to an allauth backend URL.\n     This is the URL that you need to have setup at your OAuth\n     app/client configuration. Note that this must be a backend URL\n     as providers can use POST requests to perform their callbacks,\n     which is something a frontend would not be able to handle.\n\n  3. After the authorization at the provider is completed, the\n     provider redirects to the *backend* allauth callback URL, which\n     will then redirect back to the *frontend* callback URL.\n\n  4. Your frontend is now expected to fetch the current session to\n     determine what the next course of action is. The user could be\n     authenticated at this point, or another flow is pending\n     (e.g. email verification, or, provider signup). In case of\n     errors a `?error=` is passed to the frontend callback URL.\n", "example": "https://app.project.org/account/provider/callback"}, "process": {"$ref": "#/components/schemas/Process"}}, "required": ["provider", "process", "callback_url"]}, "RequestPassword": {"type": "object", "properties": {"email": {"$ref": "#/components/schemas/Email"}}, "required": ["email"]}, "RequestLoginCode": {"type": "object", "anyOf": [{"title": "Request login code (phone)", "properties": {"phone": {"$ref": "#/components/schemas/Phone"}}, "required": ["phone"]}, {"title": "Request login code (email)", "properties": {"email": {"$ref": "#/components/schemas/Email"}}, "required": ["email"]}]}, "Reauthenticate": {"type": "object", "properties": {"password": {"$ref": "#/components/schemas/Password"}}, "required": ["password"]}, "ProviderSignup": {"allOf": [{"$ref": "#/components/schemas/BaseSignup"}]}, "PasskeySignup": {"allOf": [{"$ref": "#/components/schemas/BaseSignup"}]}, "BaseSignup": {"type": "object", "properties": {"email": {"$ref": "#/components/schemas/Email"}, "username": {"$ref": "#/components/schemas/Username"}}, "required": ["email", "username"]}, "Signup": {"allOf": [{"$ref": "#/components/schemas/BaseSignup"}, {"type": "object", "properties": {"password": {"$ref": "#/components/schemas/Password"}}, "required": ["password"]}]}, "Username": {"type": "string", "description": "The username.\n", "example": "wizard"}, "Email": {"type": "string", "description": "The email address.\n", "example": "email@domain.org"}, "Phone": {"type": "string", "description": "The phone number.\n", "example": "+314159265359"}, "AccessToken": {"type": "string", "description": "The access token.\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdW"}, "RefreshToken": {"type": "string", "description": "The refresh token.\n", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.QV30"}, "Login": {"allOf": [{"type": "object", "properties": {"password": {"$ref": "#/components/schemas/Password"}}, "required": ["password"]}, {"anyOf": [{"title": "Login by username", "properties": {"username": {"$ref": "#/components/schemas/Username"}}, "required": ["username"]}, {"title": "Login by email", "properties": {"email": {"$ref": "#/components/schemas/Email"}}, "required": ["email"]}, {"title": "Login by phone", "properties": {"phone": {"$ref": "#/components/schemas/Phone"}}, "required": ["phone"]}]}]}, "StatusOK": {"type": "integer", "enum": [200]}, "StatusAccepted": {"type": "integer", "enum": [202]}, "AuthenticatorID": {"type": "integer", "description": "Authenticator ID.\n", "example": 123}, "SocialAccountConfiguration": {"type": "object", "description": "Configuration of the Django `allauth.socialaccount` app.\n", "properties": {"providers": {"$ref": "#/components/schemas/ProviderList"}}, "required": ["providers"]}, "MFAConfiguration": {"type": "object", "description": "Configuration of the Django `allauth.mfa` app.\n", "properties": {"supported_types": {"type": "array", "description": "Matches `settings.MFA_SUPPORTED_TYPES`.\n", "items": {"$ref": "#/components/schemas/AuthenticatorType"}}}, "required": ["supported_types"]}, "UserSessionsConfiguration": {"type": "object", "description": "Configuration of the Django `allauth.usersessions` app.\n", "properties": {"track_activity": {"type": "boolean", "description": "Matches `settings.USERSESSIONS_TRACK_ACTIVITY`.\n"}}, "required": ["track_activity"]}, "ConfigurationResponse": {"type": "object", "properties": {"data": {"type": "object", "properties": {"account": {"$ref": "#/components/schemas/AccountConfiguration"}, "socialaccount": {"$ref": "#/components/schemas/SocialAccountConfiguration"}, "mfa": {"$ref": "#/components/schemas/MFAConfiguration"}, "usersessions": {"$ref": "#/components/schemas/UserSessionsConfiguration"}}, "required": ["account"]}, "status": {"$ref": "#/components/schemas/StatusOK"}}, "required": ["status", "data"], "example": {"status": 200, "data": {"account": {"authentication_method": "email"}, "socialaccount": {"providers": [{"id": "google", "name": "Google", "flows": ["provider_redirect", "provider_token"], "client_id": "123.apps.googleusercontent.com", "openid_configuration_url": "https://accounts.google.com/.well-known/openid-configuration"}]}, "mfa": {"supported_types": ["recovery_codes", "totp"]}, "usersessions": {"track_activity": false}}}}, "ResetPassword": {"type": "object", "properties": {"key": {"type": "string", "description": "The password reset key", "example": "2f-c4nqd4-e07d9bc694f9f28cd4fe92569d495333"}, "password": {"$ref": "#/components/schemas/Password"}}, "required": ["key", "password"]}, "VerifyEmail": {"type": "object", "properties": {"key": {"type": "string", "description": "The email verification key", "example": "2f-c4nqd4-e07d9bc694f9f28cd4fe92569d495333"}}, "required": ["key"]}, "VerifyPhone": {"type": "object", "properties": {"code": {"type": "string", "description": "The phone verification code", "example": "4S3H82"}}, "required": ["code"]}, "OptionalTimestamp": {"nullable": true, "$ref": "#/components/schemas/Timestamp"}, "Timestamp": {"type": "number", "description": "An epoch based timestamp (trivial to parse using: `new Date(value)*1000`)\n", "example": 1711555057.065702}, "AuthenticatorCode": {"type": "string", "description": "An authenticator code.\n", "example": "314159"}, "Code": {"type": "string", "description": "An one-time code.\n", "example": "NQ3TM5"}, "AuthenticatorType": {"type": "string", "enum": ["recovery_codes", "totp", "webauthn"], "description": "The type of authenticator.\n"}, "Password": {"type": "string", "description": "The password.\n", "example": "Alohomora!"}, "ErrorResponse": {"type": "object", "properties": {"status": {"type": "integer", "enum": [400], "example": 400}, "errors": {"type": "array", "items": {"type": "object", "properties": {"code": {"type": "string", "example": "invalid", "description": "An error code.\n"}, "param": {"type": "string", "example": "email", "description": "The name of the input parameter that was incorrect.\n"}, "message": {"type": "string", "example": "Enter a valid email address.", "description": "A human readable error message.\n"}}, "required": ["code", "message"]}}}}, "Process": {"type": "string", "description": "The process to be executed when the user successfully\nauthenticates. When set to `login`, the user will be logged into the\naccount to which the provider account is connected, or if no such\naccount exists, a signup will occur. If set to `connect`, the provider\naccount will be connected to the list of provider accounts for the\ncurrently authenticated user.\n", "enum": ["login", "connect"], "example": "login"}, "ProviderID": {"type": "string", "description": "The provider ID.\n", "example": "google"}, "ProviderAccountID": {"type": "string", "description": "The provider specific account ID.\n", "example": "goo12345"}, "User": {"type": "object", "properties": {"id": {"description": "The user ID.", "example": 123, "type": "integer"}, "display": {"description": "The display name for the user.", "example": "Magic Wizard", "type": "string"}, "email": {"description": "The email address.", "example": "email@domain.org", "type": "string"}, "has_usable_password": {"description": "Whether or not the account has a password set.", "example": true, "type": "boolean"}, "username": {"description": "The username.", "example": "wizard", "type": "string"}}, "required": ["display", "has_usable_password", "username"]}, "EmailAddress": {"type": "object", "properties": {"email": {"$ref": "#/components/schemas/Email"}, "primary": {"type": "boolean", "example": true}, "verified": {"type": "boolean", "example": false}}, "required": ["email", "primary", "verified"]}, "BaseAuthenticator": {"type": "object", "properties": {"last_used_at": {"$ref": "#/components/schemas/OptionalTimestamp"}, "created_at": {"$ref": "#/components/schemas/Timestamp"}}, "required": ["created_at", "last_used_at"]}, "TOTPAuthenticator": {"allOf": [{"$ref": "#/components/schemas/BaseAuthenticator"}, {"type": "object", "properties": {"type": {"type": "string", "enum": ["totp"]}}, "required": ["type"]}]}, "WebAuthnAuthenticator": {"allOf": [{"$ref": "#/components/schemas/BaseAuthenticator"}, {"type": "object", "properties": {"type": {"type": "string", "enum": ["webauthn"]}, "id": {"$ref": "#/components/schemas/AuthenticatorID"}, "name": {"type": "string", "example": "Master key"}, "is_passwordless": {"type": "boolean", "description": "Whether or not this authenticator represents a passkey. Absent if it is not specified.\n"}}, "required": ["type", "id", "name"]}]}, "RecoveryCodesAuthenticator": {"allOf": [{"$ref": "#/components/schemas/BaseAuthenticator"}, {"type": "object", "properties": {"type": {"type": "string", "description": "The authenticator type.\n", "enum": ["recovery_codes"]}, "total_code_count": {"type": "integer", "description": "The total number of recovery codes that initially were available.\n", "example": 10}, "unused_code_count": {"type": "integer", "description": "The number of recovery codes that are unused.\n", "example": 7}}, "required": ["type", "total_code_count", "unused_code_count"]}]}, "SensitiveRecoveryCodesAuthenticator": {"allOf": [{"$ref": "#/components/schemas/RecoveryCodesAuthenticator"}, {"type": "object", "properties": {"unused_codes": {"type": "array", "description": "The list of unused codes.\n", "items": {"$ref": "#/components/schemas/AuthenticatorCode"}}}, "required": ["unused_codes"]}]}, "AuthenticatorList": {"type": "array", "items": {"oneOf": [{"$ref": "#/components/schemas/TOTPAuthenticator"}, {"$ref": "#/components/schemas/RecoveryCodesAuthenticator"}, {"$ref": "#/components/schemas/WebAuthnAuthenticator"}]}}, "ProviderList": {"type": "array", "items": {"$ref": "#/components/schemas/Provider"}}, "Provider": {"type": "object", "properties": {"id": {"type": "string", "example": "google", "description": "The provider ID.\n"}, "name": {"type": "string", "description": "The name of the provider.\n", "example": "Google"}, "client_id": {"type": "string", "description": "The client ID (in case of OAuth2 or OpenID Connect based providers)\n", "example": "123.apps.googleusercontent.com"}, "openid_configuration_url": {"type": "string", "description": "The OIDC discovery or well-known URL (in case of OAuth2 or OpenID Connect based providers)\n", "example": "https://accounts.google.com/.well-known/openid-configuration"}, "flows": {"type": "array", "description": "The authentication flows the provider integration supports.\n", "items": {"type": "string", "enum": ["provider_redirect", "provider_token"]}}}, "required": ["id", "name", "flows"]}, "ProviderAccount": {"type": "object", "properties": {"uid": {"$ref": "#/components/schemas/ProviderAccountID"}, "display": {"type": "string", "description": "A name derived from the third-party provider account data.\n", "example": "Wizzkid"}, "provider": {"$ref": "#/components/schemas/Provider"}}, "required": ["uid", "provider", "display"]}, "EmailVerificationInfo": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "object", "properties": {"email": {"$ref": "#/components/schemas/Email"}, "user": {"$ref": "#/components/schemas/User"}}, "required": ["email", "user"]}, "meta": {"type": "object", "properties": {"is_authenticating": {"type": "boolean"}}, "required": ["is_authenticating"]}}, "required": ["status", "data", "meta"]}, "WebAuthnCredentialRequestOptions": {"type": "object", "properties": {"request_options": {"type": "object", "example": {"status": 200, "data": {"request_options": {"publicKey": {"challenge": "aOecJJtLA2e-Dj2WU-zbRoJewbQqSUPxoA9EzsUL72o", "rpId": "localhost", "allowCredentials": [], "userVerification": "preferred"}}}}}}, "required": ["request_options"]}, "WebAuthnCredentialCreationOptions": {"type": "object", "properties": {"creation_options": {"type": "object", "example": {"status": 200, "data": {"request_options": {"publicKey": {"challenge": "aOecJJtLA2e-Dj2WU-zbRoJewbQqSUPxoA9EzsUL72o", "rpId": "localhost", "allowCredentials": [], "userVerification": "preferred"}}}}}}, "required": ["creation_options"]}, "WebAuthnCredential": {"type": "object", "example": {"credential": {"type": "public-key", "id": "-J4JNfPfnLyRSMK4R...", "rawId": "-J4JNfPfnLyRSMK4R...", "authenticatorAttachment": "cross-platform", "response": {"clientDataJSON": "eyJjaGFsbGVuZ2UiOi...", "authenticatorData": "SZYN5YgO...", "signature": "MEUCIE-7sqILygPqGbrRZ4j2nqeqUU...", "userHandle": "Mg..."}, "clientExtensionResults": {}}}}}, "parameters": {"Client": {"name": "client", "in": "path", "description": "The type of client accessing the API.", "required": true, "schema": {"type": "string", "enum": ["app", "browser"]}}, "EmailVerificationKey": {"in": "header", "name": "X-Email-Verification-Key", "schema": {"type": "string"}, "required": true, "description": "The email verification key"}, "PasswordResetKey": {"in": "header", "name": "X-Password-Reset-Key", "schema": {"type": "string"}, "required": true, "description": "The password reset key"}, "SessionToken": {"in": "header", "name": "X-Session-Token", "required": false, "description": "Session token. Only needed when `client` is equal to `app`.\n", "schema": {"type": "string"}}, "PasswordLess": {"in": "query", "name": "passwordless", "required": false, "schema": {"type": "boolean"}, "allowEmptyValue": true, "description": "When present (regardless of its value), enables passwordless sign-in via a WebAuthn credential (Passkey),\nbut may enforce additional multi-factor authentication (MFA) requirements. Omit the parameter to disable.\n"}}, "responses": {"AddAuthenticatorConflict": {"description": "The account prohibits adding an authenticator, e.g. because of an unverified email address.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConflictResponse"}}}}, "Authentication": {"description": "Not authenticated.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"unauthenticated_initial": {"$ref": "#/components/examples/UnauthenticatedInitial"}, "unauthenticated_pending_2fa": {"$ref": "#/components/examples/UnauthenticatedPending2FA"}, "unauthenticated_pending_provider_signup": {"$ref": "#/components/examples/UnauthenticatedPendingProviderSignup"}, "unauthenticated_pending_email_verification": {"$ref": "#/components/examples/UnauthenticatedPendingEmailVerification"}, "reauthentication_required": {"$ref": "#/components/examples/ReauthenticationRequired"}}}}}, "Authenticators": {"description": "List of authenticators.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/AuthenticatorList"}}, "required": ["status", "data"]}}}}, "AuthenticatedByPassword": {"description": "Authenticated by password.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticatedResponse"}, "examples": {"authenticated": {"$ref": "#/components/examples/AuthenticatedByPassword"}}}}}, "AuthenticatedByCode": {"description": "Authenticated by code.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticatedResponse"}, "examples": {"authenticated": {"$ref": "#/components/examples/AuthenticatedByCode"}}}}}, "AuthenticatedByPasswordAnd2FA": {"description": "Authenticated by password and 2FA.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticatedResponse"}, "examples": {"authenticated": {"$ref": "#/components/examples/AuthenticatedByPasswordAnd2FA"}}}}}, "AuthenticationOrReauthentication": {"description": "The response indicates authentication or re-authentication is required.\n", "content": {"application/json": {"schema": {"oneOf": [{"$ref": "#/components/schemas/AuthenticationResponse"}, {"$ref": "#/components/schemas/ReauthenticationResponse"}]}}}}, "Configuration": {"description": "The django-allauth configuration.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ConfigurationResponse"}}}}, "EmailAddresses": {"description": "List of email addresses.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/EmailAddress"}}}, "required": ["status", "data"]}}}}, "EmailVerificationInfo": {"description": "Email verification information.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EmailVerificationInfo"}}}}, "Error": {"description": "An input error occurred.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}}, "Forbidden": {"description": "A forbidden response.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ForbiddenResponse"}}}}, "NotFound": {"description": "Not found.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "integer", "enum": [404]}}, "required": ["status"]}}}}, "PasswordResetInfo": {"description": "Information about the password reset key.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "object", "properties": {"user": {"$ref": "#/components/schemas/User"}}}}, "required": ["status", "data"]}}}}, "PhoneNumbers": {"description": "List of phone numbers.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PhoneNumbersResponse"}}}}, "ProviderAccounts": {"description": "List of third-party provider accounts.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/ProviderAccount"}}}, "required": ["status", "data"]}}}}, "ProviderSignup": {"description": "Information relating to the pending provider signup.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "object", "properties": {"email": {"type": "array", "items": {"$ref": "#/components/schemas/EmailAddress"}}, "account": {"$ref": "#/components/schemas/ProviderAccount"}, "user": {"$ref": "#/components/schemas/User"}}, "required": ["email", "account", "user"]}}, "required": ["status", "data"]}}}}, "ReauthenticationRequired": {"description": "The response indicates reauthentication is required.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ReauthenticationResponse"}, "examples": {"reauthentication_required": {"summary": "Reauthentication required\n", "value": {"status": 401, "data": {"user": {"id": 123, "display": "Magic Wizard", "email": "email@domain.org", "has_usable_password": true, "username": "wizard"}, "methods": [{"method": "password", "at": 1711555057.065702, "email": "email@domain.org"}, {"method": "mfa", "at": 1711555060.9375854, "id": 66, "type": "totp"}], "flows": [{"id": "reauthenticate"}, {"id": "mfa_reauthenticate"}]}, "meta": {"is_authenticated": true}}}}}}}, "RecoveryCodes": {"description": "Information on the recovery codes.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/SensitiveRecoveryCodesAuthenticator"}}, "required": ["status", "data"]}}}}, "RefreshToken": {"description": "A new access token (and optionally new refresh token).", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "object", "properties": {"access_token": {"$ref": "#/components/schemas/AccessToken"}, "refresh_token": {"$ref": "#/components/schemas/RefreshToken"}}, "required": ["access_token"]}}, "required": ["data", "status"]}}}}, "Sessions": {"description": "List of sessions.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"type": "array", "items": {"$ref": "#/components/schemas/Session"}}}, "required": ["status", "data"]}}}}, "SessionGone": {"description": "The response indicates session is invalid or no longer exists.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SessionGoneResponse"}, "examples": {"unauth": {"$ref": "#/components/examples/UnauthenticatedInitial"}}}}}, "StatusOK": {"description": "A success response.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}}, "required": ["status"]}}}}, "TooManyRequests": {"description": "Too many requests.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "integer", "enum": [429]}}, "required": ["status"]}}}}, "TOTPAuthenticator": {"description": "Information on the TOTP authenticator.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "meta": {"properties": {"recovery_codes_generated": {"description": "Whether or not recovery codes where generated automatically.", "type": "boolean"}}, "type": "object"}, "data": {"$ref": "#/components/schemas/TOTPAuthenticator"}}, "required": ["status", "data"]}}}}, "TOTPAuthenticatorNotFound": {"description": "No TOTP authenticator has been set up.\n", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"type": "integer", "enum": [404]}, "meta": {"type": "object", "properties": {"secret": {"type": "string", "description": "A TOTP secret that can be used to setup a new authenticator.\n", "example": "J4ZKKXTK7NOVU7EPUVY23LCDV4T2QZYM"}, "totp_url": {"type": "string", "description": "otpauth URI from which a QR code can be generated and scanned by OTP clients.\n", "example": "otpauth://totp/Example:alice@fsf.org?secret=JBSWY3DPEHPK3PXP&issuer=Example"}}, "required": ["secret", "totp_url"]}}, "required": ["status", "meta"]}}}}, "Unauthenticated": {"description": "There is no authenticated session.\n", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticationResponse"}, "examples": {"unauth": {"$ref": "#/components/examples/UnauthenticatedInitial"}}}}}, "Authenticated": {"description": "The user is authenticated.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuthenticatedResponse"}}}}, "WebAuthnRequestOptionsResponse": {"description": "WebAuthn credential request options.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/WebAuthnCredentialRequestOptions"}}, "required": ["status", "data"]}}}}, "WebAuthnCreationOptionsResponse": {"description": "WebAuthn credential creation options.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/WebAuthnCredentialCreationOptions"}}, "required": ["status", "data"]}}}}, "WebAuthnAuthenticator": {"description": "A WebAuthn authenticator.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/WebAuthnAuthenticator"}}, "required": ["status", "data"]}}}}, "AddWebAuthnAuthenticator": {"description": "A WebAuthn authenticator.", "content": {"application/json": {"schema": {"type": "object", "properties": {"status": {"$ref": "#/components/schemas/StatusOK"}, "data": {"$ref": "#/components/schemas/WebAuthnAuthenticator"}, "meta": {"type": "object", "properties": {"recovery_codes_generated": {"type": "boolean", "description": "Whether or not recovery codes where generated automatically.\n"}}}}, "required": ["status", "data", "meta"]}}}}}}}