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