API & SDK

Userfront core JS library

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

It can be used for the following:

#@userfront/core

A standalone library with all of the JS methods on this page.

#@userfront/toolkit

Ready-to-use authentication components for use with React, Vue, and HTML Web Components. The toolkit library also exports all of the JS methods on this page.

#Setup

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

#init (tenantId, options)

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

#tenantId stringrequired

Your workspace or tenant ID.

#options.domain string

The domain to use for all requests. Defaults to "api.userfront.com".

#addInitCallback (function)

Calls the supplied callback whenever Userfront.init() is called.

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 executed on subsequent calls to Userfront.init()

#function functionrequired

The function to call.

A JSON object with the tenantId is supplied to the callback.

#Authentication

#Rate limiting

Requests to send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse. Requests that exceed the rate limit will fail with an error message indicating the request was rate limited.

There are two kinds of rate limit: duplicate request prevention and spam prevention.

Duplicate request prevention:

Userfront will not send email or SMS messages to any user more than once in any 2 second interval. If a request was already fulfilled in the last 2 seconds, additional attempts will fail with an error message indicating the request was rate limited.

Spam prevention:

Userfront will not send an excessive number of emails or SMS messages to a user. When these spam prevention rate limits are exceeded, the user will be marked as a suspected target of spam or malicious activity, and Userfront will send no further emails or SMS messages for the following 24 hours, and fail with an error message indicating the request was rate limited for any further requests to send messages to the email address or phone number.

For newly registered users and existing users whose email address or phone number is not verified, the limits are:

  • No more than 10 messages will be sent within any 10-minute period.
  • No more than 20 messages will be sent within any 24-hour period.

When sending to an existing user's confirmed email address or phone number, the limits are:

  • No more than 20 messages will be sent within any 10-minute period.

To opt any particular user account out of rate limiting - for example, user accounts used in development and automated testing - please contact support with the user IDs to be opted out.

To match live mode behavior, rate limits are enforced in test mode, even though Userfront does not send emails or SMS messages in test mode.

#signup (options)

Registers a new user with one of the available methods.

#method stringrequired

The method for registering a new user.

  • password - Sign up with email + password

  • passwordless - Sign up with email only

  • apple - Single Sign-On (SSO) with Apple

  • azure - Single Sign-On (SSO) with Azure

  • facebook - Single Sign-On (SSO) with Facebook

  • github - Single Sign-On (SSO) with GitHub

  • google - Single Sign-On (SSO) with Google

  • linkedin - Single Sign-On (SSO) with LinkedIn

  • okta - Single Sign-On (SSO) with Okta

#email stringrequired with password & passwordless

The user's email address.

#username stringusable with password & passwordless

The user's username.

#name stringusable with password & passwordless

The user's full name.

#data objectusable with password & passwordless

The user's custom data object.

#password stringrequired with password method

The user's password.

#redirect string | boolean

Set a path to redirect to, or false to prevent redirection.

#handleTokens(tokens, data) function

Set a custom method to handle the JWT access token set upon a successful login response. See handleTokens()

#handleRedirect(redirect, data) function

Set a custom method to handle redirection upon a successful login response. See handleRedirect()

#handleMfaRequired(firstFactorToken, data) function

Set a custom method to handle an "MFA required" response. See handleMfaRequired()

#handlePkceRequired(code, data) function

Set a custom method to handle a "PKCE required" response. See handlePkceRequired()

#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
SuccessError

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

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

#Signup via Single Sign-On (SSO) methods

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

  • apple
  • azure
  • facebook
  • github
  • google
  • linkedin
  • okta

See Single Sign-On for details about SSO.


When using SSO, both the signup() method and login() method initiate the same sign-on flow.

New users are ultimately redirected to your After-signup path, while existing users are redirected to your After-login path.

#login (options)

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

#method stringrequired

The method for logging in.

  • apple - Single Sign-On (SSO) with Apple

  • azure - Single Sign-On (SSO) with Azure

  • facebook - Single Sign-On (SSO) with Facebook

  • github - Single Sign-On (SSO) with GitHub

  • google - Single Sign-On (SSO) with Google

  • linkedin - Single Sign-On (SSO) with LinkedIn

  • okta - Single Sign-On (SSO) with Okta

#email stringusable with password & passwordless

The user's email address.

#username stringusable with password method only

The user's username.

#emailOrUsername stringusable with password method only

The user's email or username.

#password stringrequired with password method

The user's password.

#token stringrequired with link method

The token= URL parameter sent in a login link.

#uuid stringrequired with link method

The uuid= URL parameter sent in a login link.

#redirect string | boolean

Set a path to redirect to, or false to prevent redirection.

#handleTokens(tokens, data) function

Set a custom method to handle the JWT access token set upon a successful login response. See handleTokens()

#handleRedirect(redirect, data) function

Set a custom method to handle redirection upon a successful login response. See handleRedirect()

#handleMfaRequired(firstFactorToken, data) function

Set a custom method to handle an "MFA required" response. See handleMfaRequired()

#handlePkceRequired(code, data) function

Set a custom method to handle a "PKCE required" response. See handlePkceRequired()

#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
SuccessError

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

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

See also: signup via passwordless method.

Return values
SuccessError

#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
SuccessError

#Login via Single Sign-On (SSO) methods

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

  • apple
  • azure
  • facebook
  • github
  • google
  • linkedin
  • okta

See Single Sign-On for details about SSO.


When using SSO, both the signup() method and login() method initiate the same sign-on flow.

New users are ultimately redirected to your After-signup path, while existing users are 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 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.

#redirect string | boolean

Manually set the path to redirect to, or false to prevent redirection.

#method stringused only with SAML

The method for logging out.

#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
SuccessError

#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 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)

Alias of updatePassword().

Return values
SuccessError

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

#password stringrequired

The new password to set for the user.

#existingPassword stringused only with jwt method

The user's existing password. If the user does not have a password yet, can be omitted.

#token stringused only with link method

The token= URL parameter sent in a password reset link.

#uuid stringused only with link method

The uuid= URL parameter sent in a password reset link.

#method string

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

#redirect string | booleanused only with link method

Manually set the path to redirect to, or false to prevent redirection.

#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
SuccessError

#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
SuccessError

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

This endpoint is rate limited. Unverified users will only be emailed once per day. Verified users can only be emailed once every ten seconds.

Return values
SuccessError

#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
SuccessError

#Custom handlers

Custom handlers give you fine-grained control during signup or login.

When registered, these handlers are called in the following situations:

  1. handleTokens(): upon successful signup or login.

  2. handleRedirect(): upon successful signup or login.

  3. handleMfaRequired(): upon "MFA required" response.

  4. handlePkceRequired(): upon "PKCE required" response.

#handleTokens (tokens, data)

Calls the provided callback method upon a successful signup or login response.

#tokens object

The response object containing the JWT token set: access token, refresh token, and ID token.

#data object

The full response object, which contains the mode, suggested redirection path, tokens, and more.

#handleRedirect (redirect, data)

Calls the provided callback method upon a successful signup or login response.

#redirect string

The URL or path to redirect to, determined by one of the following in order of precedence:

  1. A value provided in the initial method call:


    Userfront.login({redirect})

  2. A value provided in the URL querystring:


    yoursite.com/login?redirect=/path

  3. The redirectTo value returned in the response
#data object

The full response object, which contains the mode, default redirection path, tokens, and more.

#handleMfaRequired (firstFactorToken, data)

Calls the provided callback method upon an "MFA required" response.

#firstFactorToken string

The bearer token to include in the header when submitting the second factor.

#data object

The full response object, which contains the mode, firstFactorToken, default redirection path, and more.

#handlePkceRequired (authorizationCode, redirect, data)

Calls the provided callback method upon a "PKCE required" response.

#authorizationCode string

The authorization code to include when submitting the PKCE request.

#redirect string

The URL or path to redirect to, determined by one of the following in order of precedence:

  1. A value provided in the initial method call:


    Userfront.login({redirect})

  2. A value provided in the URL querystring:


    yoursite.com/login?redirect=/path

  3. The redirectTo value returned in the response
#data object

The full response object, which contains the mode, authorization code, default redirection path, and more.

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

Properties

#mode string

"live" or "test" mode.

#tenantId string

The tenant that the user record is in.

#userId string

The user's numerical ID.

#userUuid string

The user's UUID.

#email string

The user's email address.

#phoneNumber string

The user's phone number.

#name string

The user's full name.

#image string

The user's image URL.

#data object

The user's custom data object.

#username string

The user's username.

#isEmailConfirmed boolean

Whether the user has confirmed their email.

#isPhoneNumberConfirmed boolean

Whether the user has confirmed their phoneNumber.

#isMfaRequired boolean

Whether the user has required MFA for their own account.

#createdAt string

When the user record was created.

#updatedAt string

When the user record was last updated.

#isConfirmed boolean

[Deprecated] Whether the user has confirmed their email. Use isEmailConfirmed instead.

#user.update (options)

Sends a request to update the currently logged in user.

The following user attributes are editable:

#name string

The user's full name.

#username string

The user's username.

#image string

The user's image URL.

#data object

The user's custom data object.

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

#tenantId string

The 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 Concepts › JWT Access Tokens.

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

#tokens.refresh()

Refreshes the existing token set. This will update the tokens to contain the latest user information and will extend the JWT access token's expiration.