Auth0 Authentication API

openapi: 3.0.0
info:
  title: Auth0 Authentication API
  description: Auth0 Authentication API. Endpoints for authentication and authorization using OpenID Connect, OAuth 2.0, SAML, WS-Federation, and Passwordless flows.
  version: 1.0.0
servers:
- url: '{auth0_domain}'
  description: The Authentication API is served over HTTPS.
  variables:
    auth0_domain:
      description: Auth0 domain
      default: https://demo.us.auth0.com
paths:
  /authorize:
    get:
      operationId: authorize
      tags:
      - Authorize User
      summary: Auth0 Authenticate a User with a Social Provider, Database/AD/LDAP (Passive), SAML/Windows Azure AD (Passive), Authorization Code Flow, Authorization
        Code Grant (PKCE) Flow, or Implicit Flow
      description: "Use this endpoint to authenticate a user. The following flows are supported:\n  - Social Provider Authentication\n  - Database/AD/LDAP (Passive)\
        \ Authentication\n  - SAML/Windows Azure AD (Passive) Authentication\n  - Authorization Code Flow\n  - Authorization Code Grant (PKCE) Flow\n  - Implicit\
        \ Flow\n"
      parameters:
      - name: audience
        in: query
        description: The unique identifier of the target API you want to access
        schema:
          type: string
      - name: scope
        in: query
        description: The scopes which you want to request authorization for. These must be separated by a space. You can request any of the standard OpenID Connect
          (OIDC) scopes about users, such as profile and email, custom claims that must conform to a namespaced format, or any scopes supported by the target API
          (for example, read:contacts). Include offline_access to get a Refresh Token.
        schema:
          type: string
      - name: response_type
        in: query
        description: Indicates to Auth0 which OAuth 2.0 flow you want to perform. Use code for Authorization Code Grant Flow, token for Implicit Flow, or id_token
          token for both an ID Token and an Access Token.
        required: true
        schema:
          type: string
          enum:
          - code
          - token
          - id_token token
      - name: client_id
        in: query
        description: Your application's ID.
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        description: The URL to which Auth0 will redirect the browser after authorization has been granted by the user.
        schema:
          type: string
          format: uri
      - name: state
        in: query
        description: An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the application.
          This value must be used by the application to prevent CSRF attacks.
        schema:
          type: string
      - name: nonce
        in: query
        description: A string value which will be included in the ID Token response from Auth0, used to prevent token replay attacks. It is required for response_type=id_token
          token.
        schema:
          type: string
      - name: code_challenge_method
        in: query
        description: Method used to generate the challenge. The PKCE spec defines two methods, S256 and plain, however, Auth0 supports only S256 since the latter
          is discouraged.
        schema:
          type: string
          enum:
          - S256
      - name: code_challenge
        in: query
        description: Generated challenge from the code_verifier.
        schema:
          type: string
      - name: connection
        in: query
        description: The name of the connection configured to your application.
        schema:
          type: string
      - name: prompt
        in: query
        description: To initiate a silent authentication request, use prompt=none.
        schema:
          type: string
      - name: organization
        in: query
        description: ID of the organization to use when authenticating a user. When not provided, if your application is configured to Display Organization Prompt,
          the user will be able to enter the organization name when authenticating.
        schema:
          type: string
      - name: invitation
        in: query
        description: Ticket ID of the organization invitation. When inviting a member to an Organization, your application should handle invitation acceptance by
          forwarding the invitation and organization key-value pairs when the user accepts the invitation.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to the social provider specified in connection
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v2/logout:
    get:
      operationId: logout
      tags:
      - Logout
      summary: Auth0 Logout a User
      description: Use this endpoint to logout a user. If you want to navigate the user to a specific URL after the logout, set that URL at the returnTo parameter.
        The URL should be included in any the appropriate Allowed Logout URLs list.
      parameters:
      - name: returnTo
        in: query
        required: false
        description: URL to redirect the user after the logout.
        schema:
          type: string
      - name: client_id
        in: query
        required: false
        description: The client_id of your application.
        schema:
          type: string
      - name: federated
        in: query
        required: false
        description: Add this query string parameter to the logout URL, to log the user out of their identity provider, as well.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to the returnTo URL or to the first Allowed Logout URLs set in the Dashboard.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /oidc/logout:
    get:
      operationId: oidc_logout
      tags:
      - Logout
      summary: Auth0 Logout a User
      description: Use this endpoint to logout a user. If you want to navigate the user to a specific URL after the logout, set that URL at the post_logout_redirect_uri
        parameter. The URL should be included in the appropriate Allowed Logout URLs list.
      parameters:
      - name: id_token_hint
        in: query
        required: false
        description: Previously issued ID Token for the user. This is used to indicate which user to log out.
        schema:
          type: string
      - name: logout_hint
        in: query
        required: false
        description: Optional sid (session ID) value to indicate which user to log out. Should be provided when id_token_hint is not available.
        schema:
          type: string
      - name: post_logout_redirect_uri
        in: query
        required: false
        description: URL to redirect the user after the logout.
        schema:
          type: string
      - name: client_id
        in: query
        required: false
        description: The client_id of your application.
        schema:
          type: string
      - name: federated
        in: query
        required: false
        description: Add this query string parameter to log the user out of their identity provider.
        schema:
          type: string
      - name: state
        in: query
        required: false
        description: An opaque value the applications adds to the initial request that the authorization server includes when redirecting the back to the post_logout_redirect_uri.
        schema:
          type: string
      - name: ui_locales
        in: query
        required: false
        description: Space-delimited list of locales used to constrain the language list for the request. The first locale on the list must match the enabled locale
          in your tenant.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to the post_logout_redirect_uri URL or to the first Allowed Logout URLs set in the Dashboard.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /samlp/{CLIENT_ID}/logout:
    post:
      operationId: saml_logout
      tags:
      - Logout
      summary: Auth0 Logout a User
      description: Use this endpoint to log out a user from an Auth0 tenant configured as a SAML identity provider (IdP). Logout behavior is determined by the configuration
        of the SAML2 Web App addon for the application on the Auth0 tenant acting as the SAML IdP.
      parameters:
      - name: CLIENT_ID
        in: path
        required: true
        description: Client ID of your application configured with the SAML2 Web App addon.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: string
              description: SAML LogoutRequest message.
      responses:
        '200':
          description: Logout successful.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /passwordless/start:
    post:
      operationId: passwordless_start
      tags:
      - Passwordless
      summary: Auth0 Start Passwordless Flow
      description: 'You have three options for passwordless authentication: Send a verification code using email, Send a link using email, Send a verification code
        using SMS.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: The client_id of your application.
                client_assertion:
                  type: string
                  description: A JWT containing containing a signed assertion with your applications credentials. Required when Private Key JWT is your application
                    authentication method.
                client_assertion_type:
                  type: string
                  description: Use the value urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Required when Private Key JWT is the application authentication
                    method.
                client_secret:
                  type: string
                  description: The client_secret of your application. Required when the Token Endpoint Authentication Method field at your Application Settings is
                    Post or Basic. Specifically required for Regular Web Applications only.
                connection:
                  type: string
                  description: How to send the code/link to the user. Use email to send the code/link using email, or sms to use SMS.
                email:
                  type: string
                  description: Set this to the user's email address, when connection=email.
                phone_number:
                  type: string
                  description: Set this to the user's phone number, when connection=sms.
                send:
                  type: string
                  description: Use link to send a link or code to send a verification code. If null, a link will be sent.
                authParams:
                  type: object
                  description: Use this to append or override the link parameters (like scope, redirect_uri, protocol, response_type), when you send a link using
                    email.
      responses:
        '200':
          description: Successful response
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /passwordless/verify:
    post:
      operationId: passwordless_verify
      deprecated: true
      tags:
      - Deprecated > Passwordless
      summary: Auth0 Verify with Verification Code
      description: Once you have a verification code, use this endpoint to login the user with their phone number/email and verification code. This is active authentication,
        so the user must enter the code in your app.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: The client_id of your application.
                connection:
                  type: string
                  description: Use sms or email (should be the same as POST /passwordless/start)
                grant_type:
                  type: string
                  description: Use password
                username:
                  type: string
                  description: The user's phone number if connection=sms, or the user's email if connection=email.
                password:
                  type: string
                  description: The user's verification code.
                scope:
                  type: string
                  description: Use openid to get an ID Token, or openid profile email to include also user profile information in the ID Token.
      responses:
        '200':
          description: Successful response
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /oauth/token:
    post:
      operationId: oauth_token
      tags:
      - OAuth Token
      summary: Auth0 Authenticates a User Using a Verification Code, Verifies Multi-factor Authentication (MFA) Using a One-time Password (OTP), Out-of-band (OOB)
        Challenge, or a Recovery Code, or Exchanges an Authorization Code for a Token
      description: "This endpoint supports multiple methods. Depending on the method, different parameters are required in the request body. The supported methods\
        \ are:\n  - Authenticate User with verification code\n  - OTP\n  - OOB\n  - Recovery Code\n  - Authorization Code\n  - Authorization Code PKCE\n  - Client\
        \ Credentials\n  - Resource Owner Password\n  - Device Authorization\n  - Refresh Token\n  - Native Social Token Exchange\n"
      parameters:
      - in: header
        name: auth0-forwarded-for
        schema:
          type: string
        description: End-user IP as a string value. Set this if you want brute-force protection to work in server-side scenarios. For more information on how and
          when to use this header, refer to Using resource owner password from server-side.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
              - $ref: '#/components/schemas/OTP'
              - $ref: '#/components/schemas/OOB'
              - $ref: '#/components/schemas/RecoveryCode'
              - $ref: '#/components/schemas/AuthorizationCode'
              - $ref: '#/components/schemas/AuthorizationCodePKCE'
              - $ref: '#/components/schemas/ClientCredentials'
              - $ref: '#/components/schemas/ResourceOwnerPassword'
              - $ref: '#/components/schemas/DeviceAuthorization'
              - $ref: '#/components/schemas/RefreshToken'
              - $ref: '#/components/schemas/NativeSocialTokenExchange'
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/AuthenticateUserWithVerificationCode'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                  id_token:
                    type: string
                  token_type:
                    type: string
                  expires_in:
                    type: integer
                  recovery_code:
                    type: string
                  error:
                    type: string
                  error_description:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: User has yet to authorize device code or transaction failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          description: You are polling faster than the specified interval of 5 seconds
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /dbconnections/signup:
    post:
      operationId: dbconnections_signup
      tags:
      - DbConnections
      summary: Auth0 Signup with User's Credentials
      description: Given a user's credentials, and a connection, this endpoint will create a new user using active authentication. This endpoint only works for database
        connections.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: The client_id of your client.
                email:
                  type: string
                  description: The user's email address.
                password:
                  type: string
                  description: The user's desired password.
                connection:
                  type: string
                  description: The name of the database configured to your client.
                username:
                  type: string
                  description: The user's username. Only valid if the connection requires a username.
                given_name:
                  type: string
                  description: The user's given name(s).
                family_name:
                  type: string
                  description: The user's family name(s).
                name:
                  type: string
                  description: The user's full name.
                nickname:
                  type: string
                  description: The user's nickname.
                picture:
                  type: string
                  description: A URI pointing to the user's picture.
                user_metadata:
                  type: object
                  description: The user metadata to be associated with the user. If set, the field must be an object containing no more than ten properties. Property
                    names can have a maximum of 100 characters, and property values must be strings of no more than 500 characters.
      responses:
        '200':
          description: Successful response
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /dbconnections/change_password:
    post:
      operationId: dbconnections_change_password
      tags:
      - DB Connections
      summary: Auth0 Send a Change Password Email
      description: 'Send a change password email to the user''s provided email address and connection. Optionally, you may provide an Organization ID to support Organization-specific
        variables in customized email templates and to include the organization_id and organization_name parameters in the Redirect To URL. Note: This endpoint only
        works for database connections.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id:
                  type: string
                  description: The client_id of your client. We strongly recommend including a Client ID so that the email template knows from which client the request
                    was triggered.
                email:
                  type: string
                  description: The user's email address.
                connection:
                  type: string
                  description: The name of the database connection configured to your client.
                organization:
                  type: string
                  description: The organization_id of the Organization associated with the user.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: string
                example: We've just sent you an email to reset your password.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /userinfo:
    get:
      operationId: userinfo
      tags:
      - User Profile
      summary: Auth0 Returns a User's Profile
      description: Given the Auth0 Access Token obtained during login, this endpoint returns a user's profile. This endpoint will work only if openid was granted
        as a scope for the Access Token. The user profile information included in the response depends on the scopes requested. For example, a scope of just openid
        may return less information than a a scope of openid profile email.
      parameters:
      - name: access_token
        in: header
        required: true
        style: simple
        explode: false
        schema:
          type: string
        description: The Auth0 Access Token obtained during login.
        example: Bearer YOUR_TOKEN_HERE
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  sub:
                    type: string
                  name:
                    type: string
                  given_name:
                    type: string
                  family_name:
                    type: string
                  middle_name:
                    type: string
                  nickname:
                    type: string
                  preferred_username:
                    type: string
                  profile:
                    type: string
                  picture:
                    type: string
                  website:
                    type: string
                  email:
                    type: string
                  email_verified:
                    type: boolean
                  gender:
                    type: string
                  birthdate:
                    type: string
                  zoneinfo:
                    type: string
                  locale:
                    type: string
                  phone_number:
                    type: string
                  phone_number_verified:
                    type: boolean
                  address:
                    type: object
                    properties:
                      country:
                        type: string
                  updated_at:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /mfa/challenge:
    post:
      operationId: mfa_challenge
      tags:
      - MFA
      summary: Auth0 Request a Challenge for Multi-factor Authentication
      description: Request a challenge for multi-factor authentication (MFA) based on the challenge types supported by the application and user. The challenge_type
        is how the user will get the challenge and prove possession. Supported challenge types include otp for one-time password (OTP), oob for SMS/Voice messages
        or out-of-band (OOB). If OTP is supported by the user and you don't want to request a different factor, you can skip the challenge request and verify the
        multi-factor authentication with a one-time password.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mfa_token:
                  type: string
                  description: The token received from mfa_required error.
                client_id:
                  type: string
                  description: Your application's Client ID.
                client_assertion:
                  type: string
                  description: A JWT containing a signed assertion with your application credentials. Required when Private Key JWT is your application authentication
                    method.
                client_assertion_type:
                  type: string
                  description: The value is urn:ietf:params:oauth:client-assertion-type:jwt-bearer. Required when Private Key JWT is the application authentication
                    method.
                client_secret:
                  type: string
                  description: Your application's Client Secret. Required when the Token Endpoint Authentication Method field at your Application Settings is Post
                    or Basic.
                challenge_type:
                  type: string
                  description: A whitespace-separated list of the challenges types accepted by your application. Accepted challenge types are oob or otp. Excluding
                    this parameter means that your client application accepts all supported challenge types.
                authenticator_id:
                  type: string
                  description: The ID of the authenticator to challenge. You can get the ID by querying the list of available authenticators for the user as explained
                    on List authenticators below.
      responses:
        '200':
          description: Successful response
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /mfa/associate:
    post:
      operationId: mfa_associate
      tags:
      - MFA
      summary: Auth0 Associates or Adds a New Authenticator for Multi-factor Authentication (MFA).
      description: 'If the user has active authenticators, an Access Token with the enroll scope and the audience set to https://{yourDomain}/mfa/ is required to
        use this endpoint.

        If the user has no active authenticators, you can use the mfa_token from the mfa_required error in place of an Access Token for this request.

        After an authenticator is added, it must be verified. To verify the authenticator, use the response values from the /mfa/associate request in place of the
        values returned from the /mfa/challenge endpoint and continue with the verification flow.

        A recovery_codes field is included in th

# --- truncated at 32 KB (79 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/auth0/refs/heads/main/openapi/auth0-authentication-api-openapi.yml