Introduction

Below are all the functions accessible via the web core sdk.
All functions return Promises.
All code examples assume the reachfive client was instanciated and stored in a variable named client.

Core commands

checkSession

Check if an SSO session is active, and if so, authenticate the current user silently and return an Authentication Result object.

If no valid session is present, an error object is returned with a login_required error key.

Definition
client.checkSession(auth)
Example Request
client.checkSession({
  nonce: 'abcd' // The nonce links the retrieved id token with the local session
}).then(
  function (authResult) {
    // Authenticate the current user locally
  },
  function (err) {
    if (err.error === 'login_required') {
      // No active session
    } else {
      // Unexpected error
      console.error(err)
    }
  }
);

getSessionInfo

Check the state of the current's SSO session, and return an SSO session object.

Definition
client.getSessionInfo()
Example Request
cient.getSessionInfo().then(result => {
  if (result.isAuthenticated) {
    // Make something
  } else {
    // Make something else
  }
});

getUser

Retrieve user’s profile.

Arguments
  • options

    required object

    Arguments listed below.

    Show child attributes
Definition
client.getUser(options)
Example Request
client.getUser({
  accessToken: 'eyJ0eXAiOiJKV1QiL...',
  fields: 'id,givenName,familyName,email,birthdate'
})

loginFromSession

Authenticate the user from the current SSO session.

Returns

Type: Promise[void]

The promise will be rejected if no session is active.

Definition
client.loginFromSession(auth)
Example Request
client.loginFromSession({
  redirectUri: 'https://www.example.com/login/callback'
})

loginWithCustomToken

Authenticate the user with a custom token.

Arguments
  • options

    required object

    Options.

    Show child attributes
Definition
client.loginWithCustomToken(options)
Example Request
client.loginWithCustomToken({
  token: 'eyJ0eXAiOiJKV1QiL...',
  auth: {
    redirectUri: 'https://www.example.com/login/callback'
  }
})

loginWithPassword

Authenticate the user with the specified email and password.

Arguments
  • options

    required object

    Options.

    Show child attributes

Returns

Type: Promise[void]

The promise will be rejected if the login fails

Definition
client.loginWithPassword(options)
Example Request
client.loginWithPassword({
  email: 'john.doe@example.com',
  password: '...',
  auth: {
    redirectUri: 'https://www.example.com/login/callback'
  }
})

loginWithSocialProvider

Authenticate the user with the specified social provider.

Arguments
Definition
client.loginWithSocialProvider(provider, auth)
Example Request
client.loginWithSocialProvider('facebook', {
  redirectUri: 'https://www.example.com/login/callback'
})

logout

Kill current user’s SSO session.

Arguments
  • options

    object

    Options.

    Show child attributes
Definition
client.logout(options)
Example Request
client.logout({
  redirectTo: 'https://my-site.com/logout'
})

off

Removes a previously registered listener for a particular ReachFive event.

Arguments
  • eventName

    required Event

    One of event.

  • callback

    required function

    Event callback that was used with on.

Definition
client.off(eventName, callback)
Example Request
function onAuthenticated(authResult) {
  const accessToken = authResult.accessToken
  // ...
}

client.on(authenticated', onAuthenticated)

// Then later
client.off(authenticated', onAuthenticated)

on

Add a listener for a particular ReachFive event.

Arguments
  • eventName

    required Event

    One of event.

  • callback

    required function

    Event callback.

Definition
client.on(eventName, callback)
Example Request
client.on('authenticated', authResult => {
  const accessToken = authResult.accessToken;
  // ...
})

refreshTokens

Refresh user’s tokens.

Arguments
  • options

    required object

    Options.

    Show child attributes
Definition
client.refreshTokens(options)
Example Request
client.refreshTokens({
  accessToken: 'eyJ0eXAiOiJKV1QiL...'
})

requestPasswordReset

Requests a password reset for the given email. On success, an email with a reset token is sent to the user.

Arguments
  • options

    required object

    Options.

    Show child attributes
Definition
client.requestPasswordReset(options)
Example Request
client.requestPasswordReset({
  email: 'john.doe@example.com'
})

signup

Create and authenticate a new user with the specified data.

Arguments
  • options

    required object

    Options.

    Show child attributes
Definition
client.signup(options)
Example Request
client.signup({
  data: {
    givenName: 'John',
    familyName: 'Doe',
    email: 'john.doe@example.com',
    password: '...'
  },
  auth: {
    redirectUri: '{{redirectUri}}'
  }
})

startPasswordless

  • Send magic link to the user with the specified email.
  • Or send verification code to the user with the specified phone number.
  • One of email or phoneNumber is required.
Arguments
Definition
client.startPasswordless(options, auth)
Example Request
client.startPasswordless({
  authType: 'magic_link',
  email: 'john.doe@example.com'
}, {
  // ...
})

updateEmail

Update user’s email and send a verification email.

Arguments
  • options

    required object

    Arguments listed below.

    Show child attributes
Definition
client.updateEmail(options)
Example Request
client.updateEmail({
  accessToken: 'eyJ0eXAiOiJKV1QiL...',
  email: '...'
})

updatePassword

Update user’s password. To be accepted, the request must include, in addition to the new password, either:

  • A fresh accessToken
  • An accessToken and the user’s oldPassword
Arguments
  • options

    required object

    Arguments listed below.

    Show child attributes
Definition
client.updatePassword(options)
Example Request
client.updatePassword({
  accessToken: 'eyJ0eXAiOiJKV1QiL...',
  password: '...'
})

updatePhoneNumber

Update user’s phone number and send a verification code by SMS.

Arguments
  • options

    required object

    Options.

    Show child attributes
Definition
client.updatePhoneNumber(options)
Example Request
client.updatePhoneNumber({
  accessToken: 'eyJ0eXAiOiJKV1QiL...',
  phoneNumber: '+33606060606'
})

updateProfile

Update user’s profile.

Arguments
  • options

    required object

    Options.

    Show child attributes

Remarks

  • email and password fields are not modifiable with this function, expect for a new user without email (generally when not provided by the social provider).

  • phone_number field is not modifiable if sms verification code is enabled on the account settings.

Definition
client.updateProfile(options)
Example Request
client.updateProfile({
  accessToken: 'eyJ0eXAiOiJKV1QiL...',
  data: {
    givenName: 'John',
    familyName: 'Doe'
  }
})

verifyPasswordless

Authenticate the user with the specified phone number and verification code.

Arguments
Definition
client.verifyPasswordless(options, auth)
Example Request
client.verifyPasswordless({
  phoneNumber: '+33606060606',
  verificationCode: '123456'
}, {
  // ...
})

verifyPhoneNumber

Verify user's phone number with the verification code sent by SMS.

Arguments
  • options

    required object

    Options.

    Show child attributes
Definition
client.verifyPhoneNumber(options)
Example Request
client.verifyPhoneNumber({
  accessToken: 'eyJ0eXAiOiJKV1QiL...',
  phoneNumber: '+33606060606',
  verificationCode: '123456'
})

Models

AuthResult object

Object get on callback of authenticated event.

Attributes
  • accessToken

    string

    User's access token.

  • expiresIn

    number

    The lifetime in seconds of the access token.

  • idToken

    string

    User's ID Token. The ID Token is a security token that contains Claims about the Authentication of an the User. The ID Token is represented as a JSON Web Token (JWT)

  • idTokenPayload

    The payload of the ID Token. See ID Token payload.

  • tokenType

    string

    The type of the token issued. Always Bearer.

  • state

    string

    If the authentication request contained a state parameter, then the same unmodified value is returned back in this response. This value should be used by the application to prevent CSRF attacks.

Example
{
  "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...",
  "expiresIn": 86400,
  "idToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1N...",
  "idTokenPayload": {},
  "tokenType": "Bearer"
}

Authentication options

Attributes
  • responseType

    string

    Should be set to code for server-side authentication, and token for client-side authentication. 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 URL where the user will be redirected back to after authentication. This value 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.

  • state

    string

    Persist data between user being directed to the authorization server and back again. Use case : Help mitigate CSRF attacks or indicating which app's pages to redirect to after authorization. Could be Base64 encoded JSON object, JWT or nonce.

  • prompt

    string

    Specify whether social provider must prompt for reauthentication or consent.

    The defined values are:

    • none: No authentication nor consent. The user must be already authenticated in social provider.
    • login: The social provider must prompt the user for reauthentication.
    • consent: The social provider must prompt for consent.
  • nonce

    string

    String value used to associate a local session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified to the ID Token.

  • 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.

  • origin

    string

    Free text parameter describing the source of the login (Only for reporting purpose).

  • scope

    array of string

    The scopes to request, as an array of string. Optional if fetchBasicProfile is not set to false.

  • fetchBasicProfile

    boolean

    Fetch user's basic profile information when they sign in. Adds profile, email, phone and openid to the requested scopes. Defaults to true.

  • accessToken

    string

    Access token of the current user. Enables social login linking to an existing account.

  • providerScope

    string

    Only for login with social provider

    Whitespace separated list of scopes that you want to request from the social provider. Defaults to scope configured in your ReachFive's console.

  • requireRefreshToken

    boolean

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

    Settings this parameter to true is equivalent to adding the OpenID's offline_access scope value to the requested scopes.

    Only accessible if your Client’s authorization method is Post, and if the Refresh Token option is selected.

Custom Token

Custom JWT Token signed with a ReachFive Client Secret.

Attributes
  • sub

    required string

    Should match an existing ReachFive profile user id.

  • client_id

    required string

    Your ReachFive Client ID.

  • exp

    required number

    Date from now + 60 seconds.

  • nonce

    required string

    Unique id to avoid replay attacks (ex: UUID).

Example
var jwt = require('jsonwebtoken');

// sign with default (HMAC SHA256) + ReachFive Client Secret
var customToken = jwt.sign({
  sub: "AVqvOB58Fg6nZfQ0ZqXt", // ReachFive user id
  client_id: "AtnY5xDg4fbanentihip", // ReachFive Client ID
  exp: Math.floor(Date.now() / 1000) + 60, // expires in (now + 60 seconds)
  nonce: "901da78d-0642-4c5b-a67e-4d28d43e7868" // unique id to avoid replay attacks
}, 'YOUR_REACHFIVE_CLIENT_SECRET');

Events

  • authenticated. Emitted after a successful authentication
  • authentication_failed. Emitted after a failed authentication with a social provider.
  • login_failed. Emitted after a failed login with password.
  • signup_failed. Emitted after a failed signup.
  • profile_updated. Emitted after a successful profile update.
  • ready. Emitted when the sdk is fully loaded. If the sdk is already loaded, the handler is called synchronously.

Field definition

A field is either a string representing the field's key (predefined, custom or consent fields), or an object with attributes (listed below) overloading default field configuration.

Predefined fields

List of all available predefined fields:

  • email
  • phone_number
  • password
  • password_confirmation
  • given_name
  • family_name
  • gender
  • birthdate

Other available fields include custom fields and consents. These fields can be displayed using respectively custom_fields.<custom_field_key> and consents.<consent_key>.

Attributes
  • key

    required string

    Attribute's key.

  • label

    string

    Field's label.

  • placeholder

    string

    Field's placeholder.

  • required

    boolean

    Whether or not the field is required. Defaults to true.

  • defaultValue

    any

    Defaults field value.

I18n overloading

All the following keys can be overloaded per widget. The default language is EN.

Attributes
  • gender

    string

    Gender

  • givenName

    string

    First name

  • familyName

    string

    Last name

  • email

    string

    Email address

  • phoneNumber

    string

    Phone number

  • verificationCode

    string

    Verification code

  • password

    string

    Password

  • oldPassword

    string

    Old password

  • newPassword

    string

    New password

  • passwordConfirmation

    string

    Password confirmation

  • birthdate

    string

    Birth date

  • save

    string

    Save

  • changePassword

    string

    Change password

  • changeEmail

    string

    Change email

  • resetPassword

    string

    Reset password

  • send

    string

    Send

  • lastTimeYouLoggedInWith

    string

    Last time you logged in with

  • notYourAccount

    string

    Not your account?

  • unexpectedErrorOccurred

    string

    Unexpected error occurred. Please retry later.

  • confirmYourIdentity

    string

    To continue, please confirm your identity.

  • rememberMe

    string

    Remember me

  • or

    string

    or

  • back

    string

    Back

  • remove

    string

    Remove

  • login.title

    string

    Log in

  • login.submitLabel

    string

    Log in

  • login.forgotPasswordLink

    string

    Don't remember your password?

  • login.signupLinkPrefix

    string

    Do not have an account?

  • login.signupLink

    string

    Sign up

  • signup.title

    string

    Sign up

  • signup.submitLabel

    string

    Sign up

  • signup.loginLinkPrefix

    string

    Already have an account?

  • signup.loginLink

    string

    Log in

  • forgotPassword.title

    string

    Forgot password

  • forgotPassword.prompt

    string

    Enter the email address associated with your account, and we’ll email you a link to reset your password.

  • forgotPassword.backToLoginLink

    string

    Back to Login

  • forgotPassword.submitLabel

    string

    Send reset link

  • forgotPassword.successMessage

    string

    An email containing a link to update your password has been sent to you.

  • passwordless.intro

    string

    Enter your email to sign in or create an account.

  • passwordless.emailSent

    string

    We sent you a link to sign in to your email.

  • passwordless.sms.intro

    string

    Enter your phone number to sign in or create an account.

  • passwordless.sms.verification.intro

    string

    Please enter the verification code we sent to your phone.

  • passwordReset.title

    string

    Reset your password

  • passwordReset.intro

    string

    Please type your new password.

  • passwordReset.successTitle

    string

    Password updated

  • passwordReset.successMessage

    string

    Your password has been modified. Go back to login page to authenticate yourself.

  • passwordReset.loginLink

    string

    Login

  • emailEditor.intro

    string

    Please enter your new email address

  • emailEditor.successMessage

    string

    Your request has been processed successfully. Please check now your mailbox| a verification email has been sent to it.

  • phoneNumberEditor.intro

    string

    Please enter your new phone number

  • phoneNumberEditor.verification.intro

    string

    Please enter the verification code we sent to your phone.

  • socialAccounts.noLinkedAccount

    string

    No linked third-party account

  • socialAccounts.linkNewAccount

    string

    Link new account

  • passwordStrength.score0

    string

    Very weak

  • passwordStrength.score1

    string

    Weak

  • passwordStrength.score2

    string

    Medium

  • passwordStrength.score3

    string

    Good

  • passwordStrength.score4

    string

    Excellent

  • day

    string

    Day

  • month

    string

    Month

  • year

    string

    Year

  • january

    string

    January

  • february

    string

    February

  • march

    string

    March

  • april

    string

    April

  • may

    string

    May

  • june

    string

    June

  • july

    string

    July

  • august

    string

    August

  • september

    string

    September

  • october

    string

    October

  • november

    string

    November

  • december

    string

    December

  • dateFormat

    string

    mm/dd/yyyy

  • genders.male

    string

    Male

  • genders.female

    string

    Female

  • genders.other

    string

    Other

  • validation.birthdate.dayOfMonth

    string

    The day doesn't look right. Be sure to use a 2-digit number that is a day of the month.

  • validation.birthdate.year

    string

    The year doesn't look right. Be sure to use an actual date of birth with four digits.

  • validation.required

    string

    You can't leave this empty

  • validation.email

    string

    This is not a valid email.

  • validation.phone

    string

    This is not a valid phone number.

  • validation.integer

    string

    This is not a valid integer.

  • validation.float

    string

    This is not a valid float number.

  • validation.date

    string

    This is not a valid date. The expected format is 'mm/dd/yyyy'

  • validation.passwordMatch

    string

    Passwords are not the same.

  • validation.password.minLength

    string

    Short passwords are easy to guess. Try one with at least {min} characters.

  • validation.password.minStrength

    string

    Password too weak

ID Token payload

Attributes
  • iss

    string

    Issuer Identifier for the Issuer of the response.

  • sub

    string

    ReachFive's user id.

  • aud

    array of strings

    Audience(s) that this ID Token is intended for. Contain the ReachFive Client ID.

  • exp

    number

    Expiration time on or after which the ID Token is not accepted for processing. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC3339 for details regarding date/times in general and UTC in particular.

  • iat

    number

    Time at which the ID Token was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

  • authType

    string

    Authentication type.

  • name

    string

    User's full name.

  • givenName

    string

    Given name(s) or first name(s).

  • familyName

    string

    Surname(s) or last name(s).

  • profile

    string

    URL of one of the user's profile page (generally a social provider's page).

  • picture

    string

    URL of one of the user's profile picture. This URL refers to an image file (for example, a PNG, JPEG, or GIF image file).

  • email

    string

    User's email address.

  • emailVerified

    boolean

    true if the user's email address has been verified.

  • gender

    string

    User's gender. Possible values are female, male or other.

  • birthdate

    string

    User's birthday, represented as an ISO 8601 YYYY-MM-DD format.

  • locale

    string

    User's locale.

  • phoneNumber

    string

    User's primary telephone number.

  • phoneNumberVerified

    string

    true if the user's phone number has been verified.

  • address

    object

    User's primary postal address.

    Show child attributes
  • updatedAt

    string

    Date when the user was last updated.

  • newUser

    boolean

    true if this id token is delivered on a sign up.

Example
{
  "aud": ["AtnY5xDg4fbanentihip"],
  "authType": "facebook",
  "birthdate": "1983-11-13",
  "email": "john.doe@example.com",
  "emailVerified": true,
  "exp": 1512225317,
  "familyName": "Doe",
  "gender": "male",
  "givenName": "John",
  "iat": 1512138917,
  "iss": "https://example.com",
  "locale": "en_US",
  "name": "John Doe",
  "newUser": false,
  "picture": "https://graph.facebook.com/10154500298019865/picture",
  "profile": "https://www.facebook.com/app_scoped_user_id/10154500298019865/",
  "sub": "AVqvOB58Fg6nZfQ0ZqXt",
  "updatedAt": "2017-12-01T14:35:17.218Z"
}

SSO Session

Object representing the state of a SSO session

Attributes
  • isAuthenticated

    boolean

    Indicates if the current user has an active SSO session or not.

  • name

    optional string

    Full name of the authenticated user, if exists.

  • email

    optional string

    Email of the authenticated user, if exists.

  • lastLoginType

    optional string

    Last used login type of the authenticated user, if exists. Can be password, facebook, google...

  • hasPassword

    optional boolean

    Indicates if the current user, if he has an active session, has password or not.

  • socialProviders

    optional boolean

    List of the social providers used by the authenticated user, if exists.

Example
{
  "isAuthenticated": true,
  "name": "John Doe",
  "email": "john.doe@example.com",
  "lastLoginType": "facebook",
  "hasPassword": true,
  "socialProviders": ["facebook", "google"]
}

Theme options

Attributes
  • primaryColor

    string

    Change button and link default color

  • borderRadius

    string

    Add a radius for social login button and other input. Can be used to make circle social login button with inline used.

  • socialButton

    object

    Social button theming options

    Show child attributes

User profile

Attributes
  • email

    required string

    Email address.

  • password

    required string

    Password.

  • gender

    string

    One of male, female or other.

  • givenName

    string

    Given name or first name.

  • familyName

    string

    Family name or last name.

  • birthdate

    string

    Birth date represented as an ISO 8601 YYYY-MM-DD format.

  • company

    string

    Company name.

  • address

    string

    Address.

  • phoneNumber

    string

    Phone number represented as an E.164 format.

  • customFields

    object

    Custom field values represented as a JSON object.

  • consents

    object

    Consent values represented as a JSON object.

  • socialIdentities

    object

    User's social providers represented as a JSON object.

Widget instance object

This object represents the newly created widget (UI) instance.

Attributes
  • destroy

    function

    Cleanly remove the widget from its container.