Using Passwordless APIs

Passwordless APIs can be used in two scenarios:

• When implementing Universal Login 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.

If you decide to embed login, please make sure you understand the security implications.

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.

The POST /passwordless/start endpoint can be called to begin the Passwordless authentication process for both Classic Universal 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.

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 ID Token to get information about the user, or use the Access Token to call your API as normal.

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.

Auth0 rate limits and attack protection 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 client secret.

• the Trust Token Endpoint IP Header toggle is on.

For a complete explanation, read Avoid Common Issues with Resource Owner Password Flow and Attack Protection.