Auth0 OAuth Token API

openapi: 3.0.0
info:
  title: Auth0 Authentication actions OAuth Token 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
tags:
- name: OAuth Token
paths:
  /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'
components:
  schemas:
    AuthenticateUserWithVerificationCode:
      description: Authenticate a user using a verification code.
      type: object
      properties:
        grant_type:
          type: string
          description: It should be http://auth0.com/oauth/grant-type/passwordless/otp.
        client_id:
          type: string
          description: The client_id of your application.
        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: 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.
        username:
          type: string
          description: The user's phone number if realm=sms, or the user's email if realm=email.
        realm:
          type: string
          description: Use sms or email (should be the same as POST /passwordless/start)
        otp:
          type: string
          description: The user's verification code.
        audience:
          type: string
          description: API Identifier of the API for which you want to get an Access Token.
        scope:
          type: string
          description: Use openid to get an ID Token, or openid profile email to also include user profile information in the ID Token.
        redirect_uri:
          type: string
          description: A callback URL that has been registered with your application's Allowed Callback URLs.
    AuthorizationCodePKCE:
      type: object
      required:
      - grant_type
      - client_id
      - code
      - code_verifier
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For Authorization Code (PKCE), use authorization_code.
          enum:
          - authorization_code
        client_id:
          type: string
          description: Your application's Client ID.
        code:
          type: string
          description: The Authorization Code received from the initial /authorize call.
        code_verifier:
          type: string
          description: Cryptographically random key that was used to generate the code_challenge passed to /authorize.
        redirect_uri:
          type: string
          description: This is required only if it was set at the GET /authorize endpoint. The values must match.
          format: uri
    ResourceOwnerPassword:
      type: object
      required:
      - grant_type
      - client_id
      - username
      - password
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For Resource Owner Password, use password.
          enum:
          - password
        client_id:
          type: string
          description: Your application's Client ID.
        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.
        audience:
          type: string
          description: The unique identifier of the target API you want to access.
        username:
          type: string
          description: Resource Owner's identifier, such as a username or email address.
        password:
          type: string
          description: Resource Owner's secret.
        scope:
          type: string
          description: String value of the different scopes the application is asking for. Multiple scopes are separated with whitespace.
        realm:
          type: string
          description: String value of the realm the user belongs. Set this if you want to add realm support at this grant. For more information on what realms are refer to Realm Support.
    NativeSocialTokenExchange:
      type: object
      required:
      - grant_type
      - subject_token
      - subject_token_type
      - client_id
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For Token Exchange for Native Social, use urn:ietf:params:oauth:grant-type:token-exchange.
          enum:
          - urn:ietf:params:oauth:grant-type:token-exchange
        subject_token:
          type: string
          description: Externally-issued identity artifact, representing the user.
        subject_token_type:
          type: string
          description: 'Identifier that indicates the type of subject_token. Currently supported native social values are: http://auth0.com/oauth/token-type/apple-authz-code.'
        client_id:
          type: string
          description: Your application's Client ID.
        audience:
          type: string
          description: The unique identifier of the target API you want to access.
        scope:
          type: string
          description: String value of the different scopes the application is requesting. Multiple scopes are separated with whitespace.
        user_profile:
          type: string
          description: 'Optional element used for native iOS interactions for which profile updates can occur. Expected parameter value will be JSON in the form of: { name: { firstName: ''John'', lastName: ''Smith }}'
    DeviceAuthorization:
      type: object
      required:
      - grant_type
      - client_id
      - device_code
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For Device Authorization, use urn:ietf:params:oauth:grant-type:device_code.
          enum:
          - urn:ietf:params:oauth:grant-type:device_code
        client_id:
          type: string
          description: Your application's Client ID.
        device_code:
          type: string
          description: The device code previously returned from the /oauth/device/code endpoint.
    RefreshToken:
      type: object
      required:
      - grant_type
      - client_id
      - refresh_token
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. To refresh a token, use refresh_token.
          enum:
          - refresh_token
        client_id:
          type: string
          description: Your application's Client ID.
        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.
        refresh_token:
          type: string
          description: The Refresh Token to use.
        scope:
          type: string
          description: A space-delimited list of requested scope permissions. If not sent, the original scopes will be used; otherwise you can request a reduced set of scopes. Note that this must be URL encoded.
    OOB:
      description: To verify MFA using an OOB challenge, your application must make a request to /oauth/token with grant_type=http://auth0.com/oauth/grant-type/mfa-oob. Include the oob_code you received from the challenge response, as well as the mfa_token you received as part of mfa_required error.
      type: object
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For OTP MFA, use http://auth0.com/oauth/grant-type/mfa-oob.
        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.
        mfa_token:
          type: string
          description: The mfa_token you received from mfa_required error.
        oob_code:
          type: string
          description: The oob code received from the challenge request.
        binding_code:
          type: string
          description: A code used to bind the side channel (used to deliver the challenge) with the main channel you are using to authenticate. This is usually an OTP-like code delivered as part of the challenge message.
    ClientCredentials:
      type: object
      required:
      - grant_type
      - client_id
      - client_secret
      - audience
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For Client Credentials, use client_credentials.
          enum:
          - client_credentials
        client_id:
          type: string
          description: Your application's Client ID.
        client_secret:
          type: string
          description: Your application's Client Secret.
        audience:
          type: string
          description: The unique identifier of the target API you want to access.
    RecoveryCode:
      description: Some multi-factor authentication (MFA) providers (such as Guardian) support using a recovery code to login. Use this method to authenticate when the user's enrolled device is unavailable, or the user cannot receive the challenge or accept it due to connectivity issues.
      type: object
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For recovery code use http://auth0.com/oauth/grant-type/mfa-recovery-code.
        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.
        mfa_token:
          type: string
          description: The mfa_token you received from mfa_required error.
        recovery_code:
          type: string
          description: Recovery code provided by the end-user.
    AuthorizationCode:
      type: object
      required:
      - grant_type
      - client_id
      - client_secret
      - code
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For Authorization Code, use authorization_code.
          enum:
          - authorization_code
        client_id:
          type: string
          description: Your application's Client ID.
        client_secret:
          type: string
          description: Your application's Client Secret.
        code:
          type: string
          description: The Authorization Code received from the initial /authorize call.
        redirect_uri:
          type: string
          description: This is required only if it was set at the GET /authorize endpoint. The values must match.
          format: uri
    OTP:
      description: To verify MFA with an OTP, prompt the user to get the OTP code, then make a request to the /oauth/token endpoint. The request must have the OTP code, the mfa_token you received (from the mfa_required error), and the grant_type set to http://auth0.com/oauth/grant-type/mfa-otp. The response is the same as responses for password or http://auth0.com/oauth/grant-type/password-realm grant types.
      type: object
      properties:
        grant_type:
          type: string
          description: Denotes the flow you are using. For OTP MFA use http://auth0.com/oauth/grant-type/mfa-otp.
        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.
        mfa_token:
          type: string
          description: The mfa_token you received from mfa_required error.
        otp:
          type: string
          description: OTP Code provided by the user.
  responses:
    NotImplemented:
      description: Not Implemented
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string
    InternalServerError:
      description: Internal Server Error
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string
    MethodNotAllowed:
      description: Method Not Allowed
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
              error_description:
                type: string