# API reference
Client-to-server
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.
# Base URL
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.
# HTTP Status Code Summary
| 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.) |
# 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
# 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 noSignupEmail parameter above.
In test mode, Userfront does not send emails.
Response
{}# Sign up with passwordless
Register a new user with an email, and send them a login link.
If the user already exists, sends them a login link. See generate login link.
Parameters
Response
{}# 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.
Response (test mode)
{
"message": "OK",
"result": {
"link": "http://localhost:3000/login?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e&type=welcome"
}
}# 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 noSignupEmail parameter above.
Response (noSignupEmail: true)
{
"message": "OK"
}# Log in with password
Log in with a password and email/username.
Parameters
Response
{}# Update own password
Update a user's password using their valid JWT access token and their existing password.
Parameters
Response
{
"message": "OK"
}# If no password exists
If the user does not have a password (for example, if they logged in via SSO), the password and existingPassword fields are both ignored, and Userfront sends the user a password reset link.
Response (if no password exists)
{
"message": "OK",
"result": {
"to": "user@example.com",
"messageId": "18299324-bf92-4ec9-bd47-403eda5f278d",
"submittedAt": "2021-12-03T22:57:28.098Z"
}
}# Test mode
In test mode, Userfront does not send emails.
If a test user does not have a password, the API response will contain a link attribute that can be followed directly in order to set the password.
This link will direct the user to your Password reset path.
Response (if no password exists, test mode)
{
"message": "OK",
"result": {
"link": "http://localhost:3000/reset?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e"
}
}# Generate login link
Generate and send a login link email.
Note
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.
Parameters
Response
{}# 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.
Response (test mode)
{
"message": "OK",
"result": {
"link": "http://localhost:3000/login?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e&type=login"
}
}# Log in with login link
Log in using the token and uuid from a login link.
Parameters
Response
{}# 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.
# Generate password reset link
Generate and send a password reset link email.
Parameters
Response
{}# 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.
Response (test mode)
{
"message": "OK",
"result": {
"link": "http://localhost:3000/reset?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e"
}
}# 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
Response
{}# Generate account verification link
Generate and send an account verification link email.
Functionally, an account verification link works the same as a login link, so the resulting token and uuid from the email can be handled via Log in with login link.
Parameters
Response
{}# 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.
Response (test mode)
{
"message": "OK",
"result": {
"link": "http://localhost:3000/login?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e&type=verify"
}
}# 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
Response
{}