Client-to-server API reference

This documentation covers requests made by a user's browser or mobile app directly to Userfront's server.

For requests made by your server to Userfront's server using your application's API key, see the API reference for server-to-server actions.

Check out our development quickstart guide.

#REST endpoints

The Userfront API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Userfront API in test mode, which does not affect your live data. The request origin and JWT access token used to for the request determine whether the request is live mode or test mode.

#Errors

Userfront uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Userfront's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g. a token is expired) include an error code that briefly explains the error reported.

ErrorMessageDescription
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, often due to missing a required parameter.
401UnauthorizedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesn't have permissions to perform the request.
404Not FoundThe requested resource doesn't exist.
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500Server ErrorSomething went wrong on Userfront's end. (These are rare.)

#Error response format

Errors contain a statusCode, message, and error object.

The message describes what went wrong for the request, while the error object contains additional information about the error.

#Rate limiting

All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

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 requests will receive a 429 Rate Limited response.

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 send a 429 Rate Limited response to 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.

#Sign up

These actions are related to sign up such as signing up with a password, passwordless, with SSO and using customer data.

#Sign up with password

Register a new user with an email and password.

Payload parameters

#email required

The user's email address.

#password required

The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.

#username 

The user's username. If not provided, one is created automatically.

#name 

The user's first and last name.

#data 

A flexible JSON object for saving additional user data.

#isMfaRequired 

When set to true, the user must log in with MFA.

#preferredFirstFactor 

The factor preferred by the user for their first login step.

#preferredSecondFactor 

The factor preferred by the user for their second login step.

#options 

Options object.

#options.noSignupEmail 

If true, Userfront does not send a welcome or signup email when registering a new user.

post /auth/create

#Sign up with passwordless

Register a new user with an email, and send them a login link email.

If the user already exists, sends them a login link email. See send login link email.

In test mode, Userfront does not send emails. See test mode note.


All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

See the rate limiting section for details.

Payload parameters

#email required

The user's email address.

#username 

The user's username.

#name 

The user's first and last name.

#data 

A flexible JSON object for saving additional user data.

#options 

Options object.

#options.redirect 

A path to redirect the user to upon login.

#options.noSignupEmail 

If true, Userfront does not send a welcome or signup email when registering a new user.

post /auth/link

#Welcome / signup email

By default, Userfront sends new users a welcome email to confirm their account. The link in this email contains a uuid and token and works the same way as a login link.

You can disable this email with the options.noSignupEmail parameter above.

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

#Test mode (passwordless signup)

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

#Sign up with SSO

Authenticate by visiting a link to an SSO provider. The SSO provider must be configured on the Authentication page in the dashboard.

A user will be signed up using the email provided during SSO authentication.

If a user record with the email provided during SSO authentication doesn't exist, a user record will be created.

If you'd like to provide custom user data to be saved to the user data object, see Sign up with SSO using custom user data

#URL parameters

provider 

Name of SSO provider:

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

#Query parameters

#tenant_id required

Unique identifier for the tenant

#origin required

The origin of the requesting page.

#redirect 

A path to redirect the user to upon sign on.

get /auth/{provider}/login

A 302 redirect to the SSO provider for the user to authenticate.

#Sign up with SSO using custom user data

Authenticate by visiting a link to an SSO provider. The SSO provider must be configured on the Authentication page in the dashboard.

Use this endpoint to specify custom user data in the payload. Log in with SSO should be preferred otherwise.

If a user record with the email provided during SSO authentication already exists:

  • The user will be logged in using the email provided.
  • The user's data object will not be overwritten.

#URL parameters

#provider 

Name of SSO provider:

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

Payload parameters

#origin required

The origin of the requesting page.

#data 

A flexible JSON object for saving additional user data.

#options 

Options object.

#options.redirect 

A path to redirect the user to upon login.

post /auth/{provider}/login

A 303 redirect to the Userfront API which will redirect to the SSO provider for the user to authenticate.

#Log in

These actions are related to log in such as logging in with a password, a login link, a verification code, a TOTP authenticator, or SSO.

#Logging in in test mode

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

#Log in with password

Log in with a password and email/username.

Payload parameters

#password required

The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.

#emailOrUsername required

Email or username to look up for login.

#options 

Options object.

#options.noResetEmail 

By default, Userfront sends a password reset email when a user without a password attempts to log in with a password. If noResetEmail is set to true, Userfront does not send a password reset email and instead returns an error for incorrect password.

post /auth/password

#No password reset email

By default, Userfront sends a password reset link email to users when they try to log in with a password but have not yet set a password.

You can disable this email with the options.noResetEmail parameter.

When disabled, the request will return an error with the type "intended_error" for a user who does not yet have a password. This distinguishes the request from a user who has a password; their error would be "bad_request_error".

#Send login link email

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

See also: sign up with passwordless.

In test mode, Userfront does not send emails. See test mode note.


All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

See the rate limiting section for details.

Payload parameters

#email required

The user's email address.

#options 

Options object.

#options.redirect 

A path to redirect the user to upon login.

post /auth/link

#Test mode (login links)

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

#Generate link credentials without sending email

You can generate login link credentials to use in your own custom emails by using the generate link credentials endpoint.

#Log in with login link

Log in using the token and uuid from a login link.

Payload parameters

#token required

The token parameter from the email link.

#uuid required

The uuid parameter from the email link.

#linkType 

The type of link. Use "welcome" to redirectTo your after-signup path. Use any other value or leave it undefined to redirectTo your after-login path.

put /auth/link

#Send verification code

Generate and send a 6-digit verification code by SMS or email.

When using a verification code as a 2nd factor, only channel is required. See Using firstFactorToken for more.

In test mode, Userfront does not send SMS or email. See test mode note.


All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

See the rate limiting section for details.

Payload parameters

#channel required

"sms" or "email"

#email 

The user's email address. Used only when verification code is a first factor.

#phoneNumber 

Phone number in E.164 format. Used only when verification code is a first factor.

#username 

The user's username. Used only when verification code is used to register a new user.

#name 

The user's first and last name. Used only when verification code is used to register a new user.

#data 

The user's email address. Used only when verification code is used to register a new user.

#userId 

Unique numerical identifier for the user. Used only when admin is sending on behalf of another user.

#userUuid 

Unique numerical identifier for the user. Used only when admin is sending on behalf of another user.

post /auth/code

#Test mode (verification codes)

In test mode, Userfront does not send SMS messages or emails. Instead, the API response will contain the verification code directly.

#Log in with verification code

Log in using a 6-digit verification code.

When using a verification code as the 1st factor, the request must use the same channel and phoneNumber / email as were used to generate the verification code.

When using a verification code as the 2nd factor, phoneNumber / email are not required. See Using firstFactorToken for more.

Payload parameters

#channel required

"sms" or "email"

#verificationCode required

6-digit verification code.

#phoneNumber 

Phone number in E.164 format.

#email 

The user's email address.

put /auth/code

#Log in with TOTP authenticator

Log in using a code generated by a TOTP authenticator app, or with a single-use backup code.

In addition to either a totpCode or a backupCode, the request must contain either a firstFactorToken in the authorization header, or one of the following in the payload: userId, userUuid, emailOrUsername, email, username, or phoneNumber.

Payload parameters

#totpCode 

A code generated by the TOTP Authenticator application.

#backupCode 

A single-use backup code, used to log in if the TOTP device is lost.

#userId 

Unique numerical identifier for the user. Used only when TOTP is a first factor.

#userUuid 

Universal unique identifier (UUID) for the user. Used only when TOTP is a first factor.

#emailOrUsername 

Email or username to look up for login. Used only when TOTP is a first factor.

#email 

The user's email address. Used only when TOTP is a first factor.

#username 

The user's username. Used only when TOTP is a first factor.

#phoneNumber 

Phone number in E.164 format. Used only when TOTP is a first factor.

post /auth/totp

#Log in with backup code

Login with a backupCode works the same way as login with a totpCode.

Each user initially begins with 10 single-use backup codes for TOTP.

If all 10 single-use backup codes are used, the user will have set up TOTP authenticator again, at which time they will receive 10 new codes.

post /auth/totp

#Log in with SSO

Authenticate by visiting a link to an SSO provider. The SSO provider must be configured on the Authentication page in the dashboard.

A user will be logged in using the email provided during SSO authentication.

If a user record with the email provided during SSO authentication doesn't exist, a user record will be created.

If you'd like to provide custom user data to be saved to the user data object, see Sign up with SSO using custom user data

#URL parameters

provider 

Name of SSO provider:

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

#Query parameters

#tenant_id required

Unique identifier for the tenant

#origin required

The origin of the requesting page.

#redirect 

A path to redirect the user to upon sign on.

get /auth/{provider}/login

A 302 redirect to the SSO provider for the user to authenticate.

#Reset password

These actions are related to reset password such as logging in with a password, a login link, a verification code, a TOTP authenticator, or SSO.

#Send password reset email

Generate and send a password reset link email.

In test mode, Userfront does not send emails. See test mode note.


All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

See the rate limiting section for details.

Payload parameters

#email required

The user's email address.

#options 

Options object.

#options.origin 

The origin to use when requesting a link from a different origin. Must be a live mode domain.

post /auth/reset/link
Response

#Test mode (reset links)

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to reset the user's password.

#Generate link credentials without sending email

You can generate password reset link credentials to use in your own custom emails by using the generate link credentials endpoint.

#Reset password with link credentials

Reset a user's password using the token and uuid from a password reset link.

Upon success, returns a JWT access token so that the user can log in directly.

Payload parameters

#password required

The new password to set for the user. Password must be at least 16 characters OR at least 8 characters including a number and a letter.

#token required

The token parameter from the email link.

#uuid required

The uuid parameter from the email link.

put /auth/reset

#Logged in actions

Logged in actions allow a logged in user to perform actions on their own user record.

These actions are for updating existing items such as reading user info, updating a user, or verifying an email.

#Read a session

Details of the session associated with the authorization header's JWT.

The request must include the user's valid JWT access token in the Authorization header.

Payload parameters

No parameters
get /session
Response

#Read own user data

Read detailed information about the logged in user.

The request must include the user's valid JWT access token in the Authorization header.

Payload parameters

No parameters
get /self
Response

#Update user password

Update a user's password using their valid JWT access token and their existing password.

The request must include a valid JWT access token in the Authorization header.

Payload parameters

#password required

New password to set. Password must be at least 16 characters OR at least 8 characters including a number and a letter.

#existingPassword 

The user's existing (old) password. Required if the user has an existing password.

put /auth/password
Response

#If no password exists

If the user does not have a password (for example, if they logged in via SSO), the existingPassword field is ignored, and Userfront sets the password based on the password field alone.

#Update user email address

To update a user's own email address, send the new email address to the Verify an email address endpoint.

This will generate a link the user can click to verify their new email address. They will retain their old email address until the link is clicked.

#Set up TOTP authenticator

Read a user's TOTP information, including their QR code image and their remaining single-use backup codes.

The request must include a valid JWT access token or firstFactorToken in the Authorization header.

Payload parameters

No parameters
get /auth/totp
Response

#QR code

The qrCode attribute is a base-64 PNG image that can be displayed directly to the user.

#Backup codes

Each user initially begins with 10 single-use backup codes for TOTP.

You should display these backup codes to the user so that they can store them in case they lose access to their authenticator device.

If all 10 single-use backup codes are used, the user will have to re-pair their authenticator device, at which time they will receive 10 new codes.

#Remove TOTP authenticator

Remove TOTP authenticator from a user's account.

The request must contain the user's valid JWT access token in the authorization header.

Payload parameters

No parameters
delete /auth/totp
Response

#Verify an email address

Verify a user's email address by emailing them a link (default) or 6-digit verification code.

After a user verifies their email, their user record is marked isEmailConfirmed: true.

To change an existing user's email address, the request must include a valid JWT access token in the Authorization header.

When sending a link, use the Log in with login link endpoint to complete verification. When sending a verification code, use the Log in with verification code endpoint to complete verification.

In test mode, Userfront does not send emails. See test mode note.


All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

See the rate limiting section for details.

Payload parameters

#email required

The user's email address. To change a user's email address, use the new email address here along with their current userId or userUuid.

#strategy 

The strategy to use. Can be either "link" (default) or "verificationCode".

#userId 

Unique numerical identifier for the user. Not required to verify an email address. Use userId or userUuid to send an email on behalf of another user.

#userUuid 

Universal unique identifier (UUID) for the user. Not required to verify an email address. Use userId or userUuid to send an email on behalf of another user.

#options 

Options object.

#options.origin 

The origin to use when requesting a link from a different origin. Must be a live mode domain.

post /auth/verify/email
Response

#Examples of verifying an email

Verify email address with link

A user can request a login link to verify their email address. This action will send a link which can be submitted to the Login with login link endpoint.

A JWT access token is not required to request a verification link.

post /auth/verify/email
Change own email address with link

A user can request a login link to change their email address. This action will send a link which can be submitted to the Login with login link endpoint.

The request for a login link must contain a valid JWT access token when the new email address is different from the user's existing email address.

post /auth/verify/email
Admin request link sent to another user

An admin can request a login link to be sent to another user. This action will send a link which can be submitted to the Login with login link endpoint.

The request for a login link must contain the admin's valid JWT access token and the target user's userId or userUuid.

post /auth/verify/email
Verify email address with 6-digit verification code

A user can request a 6-digit verification code to verify their email address. This action will send a verification code which can be submitted to the Login with verification code endpoint.

A JWT access token is not required to request a verification code.

post /auth/verify/email
Change own email address with 6-digit verification code

A user can request a 6-digit verification code to change their email address. This action will send a verification code which can be submitted to the Login with verification code endpoint.

The request for a verification code must contain a valid JWT access token when the new email address is different from the user's existing email address.

post /auth/verify/email
Admin request verification code sent to another user

An admin can request a verification code to be sent to another user. This action will send a verification code which can be submitted to the Login with verification code endpoint.

The request for a verification code must contain the admin's valid JWT access token and the target user's userId or userUuid.

post /auth/verify/email

#Test mode (verify an email address)

In test mode, Userfront does not send emails. Instead, the API response will contain a link or verificationCode attribute that can be used directly to log in.

#Verify a phone number

Verify a user's phone number by sending them an SMS with a 6-digit verification code.

This request must include a valid JWT access token in the Authorization header.

After a user submits the verification code to the verification code endpoint, their phone number is verified and can be used in login and MFA flows.

In test mode, Userfront does not send SMS. See test mode note.


All endpoints that send emails or SMS messages to users are rate limited to mitigate spam, malicious activity, and accidental misuse.

Requests that exceed rate limits will receive a 429 Rate Limited response.

See the rate limiting section for details.

Payload parameters

#phoneNumber required

The phone number to verify. To change a user's phone number, use the new phone number here.

#userId 

Unique numerical identifier for the user. Not required to verify a phone number. Use userId or userUuid to send an SMS on behalf of another user.

#userUuid 

Universal unique identifier (UUID) for the user. Not required to verify a phone number. Use userId or userUuid to send an SMS on behalf of another user.

post /auth/verify/phone

#Examples of verifying a phone number

Verify phone number with 6-digit verification code

A user can request a 6-digit verification code to verify their phone number. This action will send a verification code which can be submitted to the Login with verification code endpoint.

The request for a verification code must contain a valid JWT access token.

post /auth/verify/phone
Change own phone number with 6-digit verification code

A user can request a 6-digit verification code to change their phone number. This action will send a verification code which can be submitted to the Login with verification code endpoint.

The request for a verification code must contain a valid JWT access token.

post /auth/verify/phone
Admin request 6-digit verification code sent to another user

An admin can request a 6-digit verification code to be sent to another user. This action will send a verification code which can be submitted to the Login with verification code endpoint.

The request for a verification code must contain the admin's valid JWT access token and the target user's userId or userUuid.

post /auth/verify/phone

#Test mode (verify phone number)

In test mode, Userfront does not send SMS messages. Instead, the API response will contain the verification code directly.

#Log out

These actions are for logging out a user.

#Log out of current session

Log out a user and invalidate their current session.

In order to invalidate the user's current session, the request must include a valid JWT access token or refresh token in the Authorization header. This token can be expired.

Payload parameters

No parameters
get /auth/logout
Response

#Log out of all sessions

Log out a user and invalidate all of their sessions.

In order to invalidate the user's sessions, the request must include a valid JWT access token or refresh token in the Authorization header. This token can be expired.

Payload parameters

No parameters
get /auth/logout/all
Response

#Multi-factor authentication

Multi-factor authentication (MFA) requires the user to use 2 separate factors when logging in. It is sometimes also called two-factor authentication (2FA)

On Userfront, any factor can be a first factor or a second factor.

#Enable MFA

MFA is enabled by default. To configure MFA options, visit the Auth flows page and configure the factors you want to use.

You can require MFA for individual users or for all users.

#Require MFA for individuals

To require MFA for an individual user, set their isMfaRequired attribute to true using either the user.update() method from the client, or the Update user endpoint from your server.

#Require MFA for all users

To require MFA for all users, visit the Auth flows page and configure the factors you want to use, then select the toggle labeled "Require MFA".

A "factor" is considered a strategy and its channel.


StrategyChannel used
PasswordEmail (for resets)
Login link / passwordlessEmail
Google, Apple, GitHub, etc. (SSO)Email
Verification codeEmail or SMS
TOTPAuthenticator app

#"MFA required" response

When MFA is required, a user's initial login request returns the "MFA required" response.

This response contains the following:

  • firstFactorToken, which can be sent in the header of the second request in order to log in and obtain a JWT access token. See Using firstFactorToken.
  • An authentication object, which contains the firstFactor that was used and an array of secondFactors that are valid for the user. For each of these second factors, isConfiguredByUser indicates whether the user has configured the factor, and, if present, isPreferredByUser indicates which factor the user prefers to log in with.
  • The isEmailConfirmed and isPhoneNumberConfirmed attributes, which indicate whether the user's email and phone number have been confirmed yet.

#Using firstFactorToken

You should include firstFactorToken in the authorization header, and from there you can use the second factor endpoint(s) as you normally would.

For endpoints that otherwise require a phoneNumber or email in the request body, you can omit these attributes when the firstFactorToken is included in the header, provided the user already has configured their phone number or email, respectively.

#Example: send SMS verification code for 2nd factor

To send an SMS verification code during the MFA login flow, include the firstFactorToken in the authorization header, and make a request to the Send verification code endpoint.

With the firstFactorToken included, the user's phoneNumber is not required.

If the user has not configured any 2nd factors for their account and does not have a phoneNumber yet, you can include the desired phoneNumber in the payload and it will be added to the user's account upon successful login.

post /auth/code

#Example: log in with SMS verification code as 2nd factor

To log in with SMS verification code during the MFA login flow, include the firstFactorToken in the authorization header, and make a request to the Log in with verification code endpoint.

With the firstFactorToken included, the response will contain the user's JWT access token for login.

put /auth/code

#Example: read TOTP authenticator information for 2nd factor

To set up TOTP authenticator during the MFA login flow, include the firstFactorToken in the authorization header, and make a request to the Set up TOTP authenticator endpoint.

For users who have not yet set up TOTP, this will return their qrCode and backupCodes, which can be used for TOTP login.

get /auth/totp

#Example: log in with TOTP authenticator as 2nd factor

To log in with TOTP authenticator during the MFA login flow, include the firstFactorToken in the authorization header, and make a request to the Log in with TOTP authenticator endpoint.

With the firstFactorToken included, the response will contain the user's JWT access token for login.

post /auth/totp

#SAML

There are three endpoints to log users in & out using SAML.

View the SAML set up guide to set up your service provider in the Userfront dashboard.


SAML is only available in live mode.

#Generate SAML token

Generate token to complete SAML login/logout.

You will need to obtain a SAML token with a valid JWT access token in the Authorization header. You will then use the token to complete the SAML flow using either of the endpoints below to log a user in or out:

  • GET /v0/auth/saml/idp/login
  • GET /v0/auth/saml/idp/logout

Payload parameters

No parameters
get /auth/saml/idp/token
Response

#Log in with SAML

Complete SAML login with token.

When a service provider requests your identity provider's Login URL, the Userfront API will redirect the client to your After-logout path where you will obtain a token using the user's JWT access token as specified in Generate SAML token.

The response is a self-submitting form containing the SAML response which sends a POST request to the service provider to complete the login process.

#Payload parameters

#tenant_id required

Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.

#token required

Generated SAML token.

#uuid required

The user's UUID.

get /auth/saml/idp/login

#Log out with SAML

Complete SAML logout with token.

When a service provider requests your identity provider's Logout URL, the Userfront API will redirect the client to your After-logout path where you will obtain a token using the user's JWT access token as specified in Generate SAML token.

The response is a self-submitting form containing the SAML response which sends a POST request to the service provider to complete the logout process.

#Query parameters

#tenant_id required

Unique identifier for the tenant

#token required

Generated SAML token.

#uuid required

The user's UUID.

get /auth/saml/idp/logout

#Refresh JWT access token

Send a user's valid refresh token to obtain a new JWT access token.

The request must include a valid refresh token in the Authorization header.

Payload parameters

No parameters
get /auth/refresh
Response