Userfront core JS library

The Userfront core JavaScript library is intended for use in frontend applications.

It can be used for the following:

#Setup

The core library must always be initialized with an account or tenant ID using the init() method.

#init (tenantId, options)

Initializes the Userfront core library with your account or tenant ID.

OptionDescription
domainThe domain to use for all requests. Defaults to api.userfront.com.

#addInitCallback (function)

Calls the supplied callback whenever Userfront.init() is called. A JSON object with the tenantId is supplied to the callback.

If addInitCallback is called more than once, callbacks are called in the order they were added (first added = first called).

Once Userfront.init() is called, the callbacks are reset and are not called on subsequent Userfront.init() calls.

#Authentication

#signup (options)

Registers a new user with one of the available methods.

OptionDescription
methodThe method for registering. Options are: password, passwordless, azure, facebook, github,google,linkedin. See below for more info on methods.
emailThe user's email address, which is required for the password and passwordless methods.
usernameThe user's username (optional). Used only with the password and passwordless methods.
nameThe user's name (optional). Used only with the password and passwordless methods.
dataThe user's custom data object (optional). Used only with the password and passwordless methods.
passwordThe user's password. Used only with the password.
redirectManually set the path to redirect to, or false to prevent redirection.

#Signup via password method

Submits an email and password to create a user.

Upon success, receives the JWT access token and adds it to the browser's cookies, then redirects the browser to the After-signup path.

Return values

#Signup via passwordless method

Creates a user and sends them an email with a link to log in. This link works with the Login via link method.

If a user with the given email address already exists, sends them an email to log in.

Return values

#Signup via azure, facebook, github,google, or linkedin methods

Initiates the sign-on flow for a given SSO provider.


When using SSO, there is no difference between the signup and login methods.

Both methods initiate the sign-on flow:

  • New users are ultimately redirected to your After-signup path
  • Existing users are ultimately redirected to your After-login path.

#login (options)

Initiates a login for a user with one of the available methods.

optiondescription
methodThe method for logging in. Options are: password, passwordless, link, azure, facebook, github, google,linkedin, and saml. See below for more info on methods.
emailThe user's email. Used with the password and passwordless methods.
usernameThe user's username. Used only with the password method.
emailOrUsernameThe user's email or username. Used only with the password method.
passwordThe user's password. Used only with the password method.
tokenThe token= URL parameter sent in a login link. Used only with the link method.
uuidThe uuid= URL parameter sent in a login link. Used only with the link method.
redirectManually set the path to redirect to, or false to prevent redirection.

#Login via password method

Sends a username or email along with a password in order to receive a JWT access token, then adds the JWT access token to the browser's cookies and redirects the browser to the After-login path.

Return values

#Login via passwordless method

Sends the user an email with a link to log in. This link works with the Login via link method.

If no user exists with the given email, this method creates a new user and sends them a login link.

See also: signup via passwordless method.

Return values

#Login via link method

This method is used to read the URL query parameters token and uuid that are sent with login link emails, and uses these parameters to log in a user.

Sends the token and uuid in order to receive a JWT access token, then adds the JWT access token to the browser's cookies and redirects the browser to the After-login path.

Return values

#Login via azure, facebook, github,google, or linkedin methods

Initiates the sign-on flow for a given SSO provider.


When using SSO, there is no difference between the signup and login methods.

Both methods initiate the sign-on flow:

  • New users are ultimately redirected to your After-signup path
  • Existing users are ultimately redirected to your After-login path.

#Login via saml method

Completes the sign-on flow for a SAML service provider.

Obtains a SAML token and redirects the browser to the Userfront API SAML login endpoint where the login response will be sent to the service provider who initiated the SAML login request.

When a user clicks a link to log in to a service provider, the service provider sends a SAML login request to the Userfront API which will then redirect the browser to your After-logout path(opens new window) where this method should be called.


When using the saml method, there is no difference between signing the user in and signing the user up.

Both cases are handled by the service provider during the sign-on flow:

  • New users are redirected to the service provider's signup process.
  • Existing users will be redirected to the service provider's path after logging in.

#logout (options)

Initiates logout for a user.

OptionDescription
redirectManually set the path to redirect to, or false to prevent redirection.
methodThe method for logging out. Currently only used for SAML.

#Default logout()

Logs a user out by invalidating their session, removes auth tokens from the browser, and then redirects the browser to the After-logout path.

Return values

#Log out of SAML service provider

Completes the SAML logout process.

Obtains a SAML token and redirects the browser to the SAML logout endpoint where the logout response will be sent to the service provider who initiated the SAML logout request.

When a user wants to log out of a service provider, the service provider sends a SAML logout request to the Userfront API which will then redirect the browser to your After-logout path(opens new window) where this method should be called.

Upon successful logout, the user will be logged out of the service provider yet remain logged in to your tenant's application.

#redirectIfLoggedIn ()

Checks if the user is logged in and, if so, redirects the browser to the After-login path.

#resetPassword (options)

Return values

#updatePassword (options)

Updates a user's password with one of the following methods:

  • The reset link credentials (token and uuid); or
  • The user's JWT access token (when logged in)

If the user does not have a password yet, then their password is created.

OptionRequiredDescription
password?The new password to set for the user.
existingPasswordThe user's existing password. Only used with the jwt method.
methodOptionally specify the link or jwt method. When not defined, updatePassword checks for the reset link credentials (token and uuid) first, followed by the user's JWT access token.
tokenThe token= URL parameter sent in the password reset link. Used only with the link method.
uuidThe uuid= URL parameter sent in the password reset link. Used only with the link method.
redirectManually set the path to redirect to, or false to prevent redirection. Used only with the link method.

#Password reset via the link method

Uses the reset link credentials (token and uuid) to reset the user's password, then logs the user in by adding their JWT access token to the browser's cookies, and finally redirects the browser to the After-login path.

Return values

#Password update via jwt method

Updates a user's password while they are logged in.

If the user has a password already, the existingPassword field must be correct.

If the user does not have a password yet (e.g. if they signed up with SSO), the existingPassword field is ignored, and the password field is set directly.

Return values

#sendLoginLink (email)

Sends an email containing a login link. This link directs the user to the After-logout path, where the login form should be located.

The user in question must exist already.

Return values

#sendResetLink (email)

Sends an email containing a password reset link. This link directs the user to the Password reset path.

The password reset link contains the token and uuid credentials, which can be used with the updatePassword method.

The user in question must exist already.

Return values

#User

#user

Returns information about the currently logged in user.

Userfront.user is intended for frontend use only, to help you display information about the user.

PropertyTypeDescription
modeStringlive or test mode
tenantIdStringThe tenant that the user record is in.
userIdIntegerThe user's numerical ID.
userUuidString (UUID)The user's UUID.
emailStringEmail address
nameStringFull name
imageStringImage URL
dataObjectCustom JSON data object
usernameStringUsername
confirmedAtStringWhen the user confirmed their email
isConfirmedBooleanWhether the user has confirmed their email
createdAtStringWhen the user record was created
updatedAtStringWhen the user record was last updated

#user.update (options)

Sends a request to update the currently logged in user.

The following user attributes are editable:

PropertyType
nameString
imageString
usernameString
dataObject

#user.hasRole (roleName, options)

Helper method to determine if the logged in user has a given role in the authorization object of their JWT access token.

Returns true if the role is present, or false if not present.

user.hasRole() should only be used to show or hide public elements like buttons or badges.

Sensitive information should always rely on server-side checks.

OptionDescription
tenantIdThe tenant to check against. Defaults to the tenantId from Userfront.init(tenantId)

#Tokens

#tokens.accessToken

Returns the JWT access token.

Your frontend application can send the access token to your server in order to authenticate a user and provide information about their access levels. For more information, see Tokens & Access.

#tokens.accessTokenName

Returns the name of the cookie that holds the JWT access token.

#tokens.idToken

The ID token is not intended for authentication or access control.

It is used client-side as a verifiable copy of the user's data. Typically it is easier to reference the user object instead.

Returns the JWT ID token.

#tokens.idTokenName

Returns the name of the cookie that holds the JWT ID token.