startPasswordless | Core JS SDK | ReachFive Documentation

About this command

Starts passwordless flow by sending an email or SMS to the user with a single-use auth code or access token (depending on the response type).

The Passwordless feature must be enabled on your ReachFive Console account.
The SMS feature must be enabled on your ReachFive Console account if the profile can choose a phone number to login.

PKCE expects the same client context to complete both steps of the exchange. This means that if a user starts the flow on one device and then tries to complete it on a different device (e.g., by switching from mobile to tablet), the exchange fails.

Examples

With an email
With a phone number
MFA

client.startPasswordless(
  {
    authType: 'magic_link',
    email: 'john.doe@example.com'
  },
  {
    redirectUri: 'https://www.example.com/login/callback'
  }
)

client.startPasswordless({
    authType: 'sms',
    phoneNumber: '+33612345678'
})

client.startPasswordless({
    authType: 'sms',
    stepUp: '3y8HnXfn7Y...w9iuF2ele9LCuk'
})

Parameters

Standard Passwordless
MFA

params PasswordlessParams

The parameters for passwordless authentication.

authType string

The type of passwordless authentication.

Allowed values: * magic_link * sms

email string

The primary email address of the profile.

phoneNumber string

The primary phone number of the profile.

Both the international format and the national conventions of the account’s country are accepted if configured in account settings.

captchaToken string

Pass along the response token you have received from reCAPTCHA. See Google’s documentation on how to obtain it.

Defaults to null.

options AuthOptions

List of authentication options

responseType string

The desired OAuth2 grant type. Use code to request an authorization code (recommended) or token for a token set (implicit grant, discouraged).

Defaults to code when redirectUri is provided, and to token otherwise. For messenger account linking, responseType should be set to messenger_code.

redirectUri string

The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified state string will also be included.

This parameter is required with code response type and defaults to the current page with token response type. For messenger account linking, redirectUri should be set with the redirect_uri query param provided by Facebook on URL.

redirectUri is still required when setting useWebMessage to true despite there being no redirection involved.

state string

An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

The parameter should be used for preventing cross-site request forgery as described in Section 10.12 of RFC 6749.

prompt string

Specify whether the flow should explicitly prompt the user for reauthentication or not.

This applies to the Login with session flow where a session cookie is provided.

In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, prompt is handled by the OP and we redirect to the OP because of this.

The defined values are:

none: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent.

If no value for prompt is specified, none is the default value for non-orchestrated flows. For orchestrated flows, if no value for prompt is specified, users are redirected to the defined Login URL with their orchestration token.

login: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the redirect_uri or client-configured login URL (if no redirect_uri is specified).
consent: The flow should prompt for consent, otherwise an error must be returned to the client (consent_required).

nonce string

String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See Section 15.5.2 of OpenID Connect for more implementation details.

persistent boolean

When persistent is true, the session duration configured in the ReachFive Console (Settings Security SSO) applies.

If persistent is not set or is false, the default session duration of 1 day applies.

Defaults to true.

popupMode boolean

Whether or not to use popup mode.

Defaults to false.

This mode is not recommended due to known bugs in Android or Firefox in iOS.

useWebMessage boolean

When set to true, the SDK will leverage the web_message response mode in order to avoid having to redirect the user-agent to obtain the authorization response.

Defaults to false. If set to true and responseType is code, the authorization code will be automatically exchanged at the token endpoint along with any potential code_verifier.

origin string

Free text parameter describing the source of the login (only for reporting purposes).

scope string[]

List of space-delimited, case-sensitive strings representing the requested scope.

Optional if the fetchBasicProfile option is set to true and the profile, email, phone and openid scope values are allowed in client configuration.

fetchBasicProfile boolean

Fetch basic user profile information when they sign in. Automatically adds profile, email, phone and openid to the requested scope.

Defaults to true.

accessToken string

Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old).

providerScope string

List of space-delimited, case-sensitive strings representing the requested scope at the social provider.

Defaults to the scope configured for the given provider in your ReachFive console.

Only for login with social provider.

requireRefreshToken boolean

If set to true, an OAuth 2.0 Refresh Token will be present in the token response.

Defaults to false.

Fetch user basic profile information when they sign in. Adds profile, email, phone and openid to the requested scope.

Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The Refresh Token option must also be selected.

returnProviderToken boolean

Boolean that specifies whether you should return the provider access token.

Defaults to false.

If set to true, you retrieve the provider and provider access token as part of the authentication result.

params PasswordlessParams

The parameters for passwordless authentication.

authType string

The type of passwordless authentication.

sms

stepUp string

The step up token for verification.

captchaToken string

Pass along the response token you have received from reCAPTCHA. See Google’s documentation on how to obtain it.

Defaults to null.

options AuthOptions

List of authentication options

responseType string

The desired OAuth2 grant type. Use code to request an authorization code (recommended) or token for a token set (implicit grant, discouraged).

Defaults to code when redirectUri is provided, and to token otherwise. For messenger account linking, responseType should be set to messenger_code.

redirectUri string

The absolute URI the user-agent will be redirected to following flow completion. It will either carry the response type, or the appropriate error in case of failure. Any specified state string will also be included.

This parameter is required with code response type and defaults to the current page with token response type. For messenger account linking, redirectUri should be set with the redirect_uri query param provided by Facebook on URL.

redirectUri is still required when setting useWebMessage to true despite there being no redirection involved.

state string

An opaque value used to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client.

The parameter should be used for preventing cross-site request forgery as described in Section 10.12 of RFC 6749.

prompt string

Specify whether the flow should explicitly prompt the user for reauthentication or not.

This applies to the Login with session flow where a session cookie is provided.

In a Social Login (SLO) flow, the session management is partially delegated to the target OIDC provider (OP) and hence, prompt is handled by the OP and we redirect to the OP because of this.

The defined values are:

none: Require that no user interaction take place. This is typically used to silently check for existing authentication and/or consent.

If no value for prompt is specified, none is the default value for non-orchestrated flows. For orchestrated flows, if no value for prompt is specified, users are redirected to the defined Login URL with their orchestration token.

login: The flow should prompt the user for reauthentication. The existing session is invalidated and the user is redirected to the redirect_uri or client-configured login URL (if no redirect_uri is specified).
consent: The flow should prompt for consent, otherwise an error must be returned to the client (consent_required).

nonce string

String value used to associate a client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token. Sufficient entropy must be present in the nonce values used to prevent attackers from guessing values. See Section 15.5.2 of OpenID Connect for more implementation details.

persistent boolean

When persistent is true, the session duration configured in the ReachFive Console (Settings Security SSO) applies.

If persistent is not set or is false, the default session duration of 1 day applies.

Defaults to true.

popupMode boolean

Whether or not to use popup mode.

Defaults to false.

This mode is not recommended due to known bugs in Android or Firefox in iOS.

useWebMessage boolean

When set to true, the SDK will leverage the web_message response mode in order to avoid having to redirect the user-agent to obtain the authorization response.

Defaults to false. If set to true and responseType is code, the authorization code will be automatically exchanged at the token endpoint along with any potential code_verifier.

origin string

Free text parameter describing the source of the login (only for reporting purposes).

scope string[]

List of space-delimited, case-sensitive strings representing the requested scope.

Optional if the fetchBasicProfile option is set to true and the profile, email, phone and openid scope values are allowed in client configuration.

fetchBasicProfile boolean

Fetch basic user profile information when they sign in. Automatically adds profile, email, phone and openid to the requested scope.

Defaults to true.

accessToken string

Access token of the current user. Enables social login linking to an existing account with a fresh token (less than 5 minutes old).

providerScope string

List of space-delimited, case-sensitive strings representing the requested scope at the social provider.

Defaults to the scope configured for the given provider in your ReachFive console.

Only for login with social provider.

requireRefreshToken boolean

If set to true, an OAuth 2.0 Refresh Token will be present in the token response.

Defaults to false.

Fetch user basic profile information when they sign in. Adds profile, email, phone and openid to the requested scope.

Refresh Tokens are only available with confidential Clients (with a configured authentication method) or for public Clients that enforce PKCE in the authorization code grant. The Refresh Token option must also be selected.

returnProviderToken boolean

Boolean that specifies whether you should return the provider access token.

Defaults to false.

If set to true, you retrieve the provider and provider access token as part of the authentication result.

Response

Type: Promise[void]

Next step (MFA flow)

The next step after the startPasswordless method in the MFA flow is:

verifyMfaPasswordless

See the dedicated MFA guide for more details.