Start Passwordless Login

This API has been available since 1.11.0

This API allows you to generate a passwordless code that can be used to complete login. This is the first step in completing a passwordless login.

If you plan to utilize the FusionAuth login page then you will not need to use this API. Instead, once passwordless authentication is enabled for the FusionAuth Application, a new button will be presented to the user on the login page which will allow them to request an email.

Request#

Generate a passwordless login code

POST/api/passwordless/start

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See Making an API request using a Tenant Id for additional information.

Request Body#

applicationIdStringrequired

The unique Id of the Application you are requesting to log into.

loginIdStringrequired

The login identifier of the user. The login identifier can be one of the following (see loginIdTypes for information on which of these identifiers will be used):

Email address
Phone number (if phoneNumber is included in loginIdTypes)
Username

For email and username, the value will be used exactly as provided to resolve a user. If the provided value contains leading or trailing white space, these characters will not be removed, and then would only match if the values stored in FusionAuth also contain these same leading or trailing spaces.

For phoneNumber, loginId can be any valid phone number (in E.164, national, or international format) and FusionAuth will canonicalize the value. The User will be resolved if the user's E.164 formatted phone number matches the canonical E.164 phone number from loginId. If no country code is provided, a US/NANP country code of 1 is assumed.

If you are using the Send Passwordless Login API with the code returned by this call, that API will send a message using a delivery method appropriate for the loginId used here. If you supplied a username or email address loginId, the message will be sent via email. If you supplied a phone number loginId then the message will be delivered via an SMS messenger.

loginIdTypesArray<String>optionalDefaults to [email, username]Available since 1.59.0

The identity types that FusionAuth will compare the loginId to. Can be one or more of the following:

email
phoneNumber
username

The order is significant. If ["email", "username"] is supplied with a loginId value of terry@example.com, then a user with terry@example.com as their email address will match first before any user with terry@example.com as their username.

stateObjectoptional

An optional object that will be returned un-modified when you complete the passwordless login request. This may be useful to return the user to particular state once they complete login using the passwordless code.

loginStrategyStringoptionalAvailable since 1.59.0

The process by which the user will complete the passwordless login. The possible values are:

ClickableLink - send the user a code with a clickable link.
FormField - send the user a short code intended to be manually entered into a form field.

If not specified, prior to version 1.64.0, the default value depends upon the loginIdType of loginId:

email address or username - ClickableLink
phone number - FormField

If not specified, in version 1.64.0 or greater, the default value depends upon the loginIdType of loginId and:

if email address or username - application.passwordlessConfiguration.emailLoginStrategy, which defaults to ClickableLink
if phone number - application.passwordlessConfiguration.phoneLoginStrategy, which defaults to FormField

Example Request JSON

{
  "applicationId": "10000000-0000-0002-0000-000000000001",
  "loginId": "jared@piedpiper.com",
  "loginIdTypes": [
    "email"
  ],
  "state": {
    "client_id": "10000000-0000-0002-0000-000000000001",
    "redirect_uri": "https://piedpiper.com/callback",
    "response_type": "code",
    "scope": "openid",
    "state": "CSRF123"
  }
}

Response#

Response Codes

Code	Description
200	The request was successful.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
404	The user was not found. The response will be empty.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.

Response Body#

codeString

The unique code used to complete the login request.

Example Response JSON

{
  "code": "CynAUMCHLxCCAWyHXOVWPQd8ZY0a6U0e3YpYkT0MNxs"
}