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.
#Just getting started?
Check out our development quickstart guide.
#REST endpoints
The Userfront API is organized around REST(opens new window). Our API has predictable resource-oriented URLs, accepts JSON-encoded(opens new window) 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.
https://api.userfront.com
#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.
200 - OK | Everything worked as expected. |
400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |
401 - Unauthorized | No valid API key provided. |
402 - Request Failed | The parameters were valid but the request failed. |
403 - Forbidden | The API key doesn't have permissions to perform the request. |
404 - Not Found | The requested resource doesn't exist. |
429 - Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
500 - Server Error | Something 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.
#Logged in actions
Logged in actions allow a logged in user to perform actions on their own user record.
#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.
Parameters
#Authentication actions
Authentication actions allow a user to sign up, log in, perform password resets, and carry out other useful interactions with your application.
Most of these actions are also implemented with helper functions in the Core JS library.
#Sign up with password
Register a new user with an email and password.
Parameters
The user's email address.
The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
The user's username. If not provided, one is created automatically.
The user's first and last name.
A flexible JSON object for saving additional user data.
Unique identifier for the tenant.
Options object.
If true, Userfront does not send a welcome or signup email when registering a new user.
#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
that allow login 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.
#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.
Parameters
The user's email address.
The user's username.
The user's first and last name.
A flexible JSON object for saving additional user data.
Unique identifier for the tenant.
Options object.
A path to redirect the user to upon login.
If true, Userfront does not send a welcome or signup email when registering a new user.
#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.
#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.
#Log in with password
Log in with a password and email/username.
Parameters
The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
Email or username to look up for login.
Unique identifier for the tenant.
Options object.
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.
#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"
.
#Update own 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.
#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 own email address
To update a user's own email address, send the new email address to the send account verification email 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.
#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.
#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.
#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.
#Send verification code
Generate and send a 6-digit verification code by SMS or email.
#Test mode
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.
The request must use the same channel
and phoneNumber
/ email
as were used to generate the verification code.
#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 in the Authorization
header.
Parameters
#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.
#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 one of the following to identify the user: userId
, userUuid
, emailOrUsername
, email
, username
, or phoneNumber
.
Parameters
Unique identifier for the tenant.
A code generated by the TOTP Authenticator application.
A single-use backup code, used to log in if the TOTP device is lost.
Unique identifier for the user.
Unique identifier for the user.
Email or username to look up for login.
The user's email address.
The user's username.
Phone number in E.164 format.
#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.
#Log in with SSO
Log in using an SSO provider by visiting a link for that provider.
The SSO provider must already be configured.
#Provider
The :provider
value should be the lowercased name of the SSO provider.
For example: google
, github
, linkedin
, facebook
, or azure
.
#Query strings
Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.
The origin of the requesting page.
A path to redirect the user to upon sign on.
#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.
Parameters
#Send password reset email
Generate and send a password reset link email.
#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 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.
Parameters
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.
The token parameter from the email link.
The uuid parameter from the email link.
Unique identifier for the tenant.
#Send account verification email
Generate and send an account verification link email.
After a user follows the account verification link, their user record is marked isConfirmed: true
.
You can process the account verification link's token
and uuid
credentials the same way as login link credentials: with Log in with login link.
To add a new email address for a user, the request must include a valid JWT access token in the Authorization
header.
If the user submits a new email address, their user record is updated after they follow the account verification link sent to the new email address.
Parameters
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.
The user's ID. Must include userId or userUuid.
The user's UUID. Must include userId or userUuid.
Unique identifier for the tenant.
Options object.
The origin to use in the link. Must be a live mode domain.
#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.
#Verify a phone number
To add a new phone number for a user, the 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.
Parameters
The user's phone number. To change a user's phone number, use the new phone number here along with their current userId or userUuid.
The user's ID. Must include userId or userUuid.
The user's UUID. Must include userId or userUuid.
Unique identifier for the tenant.
#Test mode
In test mode, Userfront does not send SMS messages. Instead, the API response will contain the verification code directly.
#Log out
Log a user out 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.
Parameters
#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.
A "factor" is considered a strategy and its channel.
Strategy | Channel used |
---|---|
Password | Email (for resets) |
Login link / passwordless | |
Google, Apple, GitHub, etc. (SSO) | |
Verification code | Email or SMS |
TOTP | Authenticator app |
#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".
#"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 thefirstFactor
that was used and an array ofsecondFactors
that are valid for the user.
#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.
#Example: read TOTP authenticator information
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.
#Example: log in with TOTP authenticator
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.
#SAML
There are three endpoints to log users in and 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
Parameters
#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(opens new window) 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.
#Parameters
Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.
Generated SAML token.
The user's UUID.
#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(opens new window) 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.
#Parameters
Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.
Generated SAML token.
The user's UUID.