APIs can be used in two scenarios:
  • When implementing and you want to customize the login page using auth0.js to interact with Auth0.
  • When you want to embed the login flow in your application.
To learn more about how to implement Passwordless for Universal Login and Embedded login for different scenarios, read Passwordless Authentication with Universal Login or Passwordless Authentication with Embedded Login.

​
Passwordless endpoints

​
POST /passwordless/start

You must enable the Passwordless OTP grant at Auth0 Dashboard > Applications > Applications in your application’s settings under Advanced Settings > Grant Types.
The POST /passwordless/start endpoint can be called to begin the Passwordless authentication process for both Classic Login and Embedded Login. Depending on the parameters provided to the endpoint, Auth0 begins the user verification process by sending one of the following:
  • A single-use code via email or SMS message
  • A single-use link via email
The API call must have the following structure: 
POST https://{yourDomain}/passwordless/start
Content-Type: application/json
{
  "client_id": "{yourClientID}",
  "client_secret": "{yourClientSecret}", // For Regular Web Applications
  "connection": "email|sms",
  "email": "{email}", //set for connection=email
  "phone_number": "{phoneNumber}", //set for connection=sms
  "send": "link|code", //if left null defaults to link
  "authParams": { // any authentication parameters that you would like to add
    "scope": "openid",     // used when asking for a magic link
    "state": "{yourState}"  // used when asking for a magic link, or from the custom login page
  }
}
If you use a magic link, users will receive a link generated by the Authentication API. Users will select the link and trigger a call to {yourAuth0Tenant}.auth0.com/passwordless/verify-redirect. Auth0 will redirect the user to the application, and the user will be logged in. If you use a code, your application will need to prompt for that code, and then you should use the /oauth/token endpoint, or the passwordlessLogin method in the Auth0.js SDK to exchange that code for authentication tokens.

​
POST /oauth/token

If you are implementing passwordless for Native Applications or Regular Web Applications, you need to use /oauth/token to exchange the OTP code for authentication tokens. You cannot use this endpoint from Single Page Applications. To achieve this you first need to enable the Passwordless OTP grant for your application at Auth0 Dashboard > Applications > Applications in your application’s settings under Advanced Settings > Grant Types. The user will receive the OTP code and your Native or Web application will prompt the user for it. When the user enters the code, you can complete the authentication flow by calling the /oauth/token endpoint with the following parameters: 
POST https://{yourAuth0Domain}/oauth/token
Content-Type: application/json
{
  "grant_type" : "http://auth0.com/oauth/grant-type/passwordless/otp",
  "client_id": "{yourAuth0ClientID}",
  "client_secret": "{yourClientSecret}", // only for web apps, native apps don’t have a client secret
  "username":"<email address>", // or "<phone number>"
  "otp": "CODE",
  "realm": "email", // or "sms" 
  "audience" : "your-api-audience", // in case you need an access token for a specific API
  "scope": "openid profile email" // whatever scopes you need
}
If all goes well, Auth0 will return a response similar to the following: 
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"eyJz93a...k4laUWw",
"refresh_token":"GEbRxBN...edjnXbL",
"id_token":"eyJ0XAi...4faeEoQ",
"token_type":"Bearer",
"expires_in":86400
}
You can then decode the to get information about the user, or use the to call your API as normal.

​
Using Auth0.js

When implementing Passwordless Authentication in Single Page Applications or in a customized Universal Login page, you should use Auth0.js and the included passwordlessLogin method. The implementation is complex, so we recommend that you use the library instead of calling the APIs directly.

​
Rate limiting in passwordless endpoints

Auth0 rate limits and features only consider the IP from the machine that is making the API call. When the API call is made from a backend server, you usually want Auth0 to consider the IP from the end user, not the one from the server. Auth0 supports specifying an auth0-forwarded-for header in API calls, but it is only considered when:
  • the API call is made for a confidential application.
  • the API call includes the .
  • the Trust IP Header toggle is on.
For a complete explanation, read Avoid Common Issues with Resource Owner Password Flow and Attack Protection.

​
Customize MFA

Customizable MFA with the Resource Owner Password Grant, Embedded, or Refresh Token flows is in Early Access. To learn more, read Product Release Stages. To participate in the early access, contact Auth0 Support.
Customize with the Passwordless API. When your application calls /oauth/token endpoint to request an access token, the returns an mfa_required error which provides:
  • The mfa_token you need to call the MFA API for enrollment and challenges.
  • The mfa_requirements parameter, which provides the factor type your application supports for challenges. 
{
  "error": "mfa_required",
  "error_description": "Multifactor authentication required",
  "mfa_token": "Fe26...Ha",
  "mfa_requirements": {
    "challenge": [
      { "type": "otp" },
      { "type": "push-notification" },
      { "type": "phone" },
      { "type": "recovery-code" }
    ]
  }
}
Use the mfa_token to call the mfa/authenticator endpoint to list all factors the user has enrolled and match the same type your application supports. You also need to obtain the matching authenticator_type to issue challenges: 
[
  {
    "type": "recovery-code",
    "id": "recovery-code|dev_qpOkGUOxBpw6R16t",
    "authenticator_type": "recovery-code",
    "active": true
  },
  {
    "type": "otp",
    "id": "totp|dev_6NWz8awwC8brh2dN",
    "authenticator_type": "otp",
    "active": true
  }
]
Enforce the MFA challenge by calling the request/mfa/challenge endpoint. Further customize your MFA flow with Auth0 Actions. To learn more, read Actions Triggers: post-challenge - API Object.