Server-to-server API reference
This documentation covers requests made by your server to Userfront's server using an API key.
For requests that end users can make directly, such as signup, login, password reset, and more, see the API reference for client-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 API key you use to authenticate the request determines whether the request is live mode or test mode.
#Authentication
The Userfront API uses API keys to authenticate requests. You can view and manage your API keys in the Userfront Dashboard.
Test mode keys have the prefix uf_test_
and live mode keys have the prefix uf_live_
.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Bearer Auth. Provide your API key in the header of each request as:
Authorization: Bearer your_api_key
.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
#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.
Error | Message | Description |
---|---|---|
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.) |
#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.
#Users
Users are the user records within your workspace or within your workspace's tenants.
You can create, read, update, and delete a user with standard REST operations.
Additionally, there are POST operations for inviting a user to a tenant, creating or updating a user (if you don't know whether they already exist), and marking a user as "active" for data purposes.
There are also 2 endpoints for searching all users in a tenant: one via GET and one via POST.
#Create user
Creates a new user.
If you want to import or create many users, see User imports.
Payload parameters
The user's email address.
The user's username. If not provided, one is created automatically.
The user's first and last name.
The user's profile image URL.
A flexible JSON object for saving additional user data.
When set to true, the user must log in with MFA.
The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
#Read user
Read a user record by its userId
.
Payload parameters
#Update user
Updates the specified user by setting the values of the parameters passed. Any parameters not provided will be left unchanged. For example, if you pass the name
parameter, that becomes the user's name to be used in the future.
This request accepts mostly the same arguments as the user creation call.
Payload parameters
Unique numerical identifier for the user.
The user's email address.
Phone number in E.164 format.
The user's username.
The user's first and last name.
The user's profile image URL.
When set to true, the user will not be able to log in or obtain new access tokens.
A flexible JSON object for saving additional user data.
The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
When set to true, the user must log in with MFA.
The factor preferred by the user for their first login step.
The factor preferred by the user for their second login step.
#Delete user
#Search users
Search users within a tenant. Responses contain 24 results per page.
Payload parameters
The order in which to return the results. Can be ascending or descending for the following: lastActiveAt (default), createdAt, updatedAt, name, or username. For example: createdAt_ASC or name_DESC.
The page number of results to return.
A filter object for returning user results.
#Filter options
The filters
object has a top-level conjunction
that applies to one or more filterGroups
.
The "and"
conjunction returns users who meet all of the criteria, while the "or"
conjunction returns users who meet any one of the criteria.
Each filter
has the following options:
#attr
The attribute to search, such as email
or createdAt
. For attributes in the data
object, use data.myAttr
.
#type
The data type of the attribute. Can be string
, boolean
, number
, date
, or array
.
#comparison
The desired criteria for returned users.
Type | Comparisons |
---|---|
string | is contains does not contain starts with ends with is unknown has any value |
boolean | is is not |
date | before after between less than (days ago)more than (days ago) |
number | is more than less than |
array | contains does not contain any |
#value
The value to be compared. Should make sense in the context of the type
and comparison
.
#Example searches
Users created in the last week
Users named John who were last active less than 30 days ago
Users with example.com in their email, or who have "Example" as a custom data attribute, sorted by username
#Searching roles
To search for users with a specific role use "tenantId: role name"
, or to search for users with any role in the tenant, use "tenantId"
.
Users with an admin role in the demo tenant (tenantId = "demo1234")
Users with any role in the demo tenant (tenantId = "demo1234")
#Invite User
Invite a user by email address.
This endpoint creates a user, then sends them an email with a link to log in (default) or set their password (see options.type).
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
Unique numerical identifier for the user.
The user's email address.
The user's username. If not provided, one is created automatically.
Phone number in E.164 format.
The user's first and last name.
The user's profile image URL.
When set to true, the user will not be able to log in or obtain new access tokens.
A flexible JSON object for saving additional user data.
When set to true, the user must log in with MFA.
The factor preferred by the user for their first login step.
The factor preferred by the user for their second login step.
The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
Whether the user's email is confirmed.
Whether the user's phoneNumber is confirmed.
Options object.
The type of link to send in the invitation email.
The length of time before the invitation link expires.
options.type
Use options.type = "reset"
to send the invitation email with a link to your Password Reset Path. For example:
/reset?uuid=...&token=...&type=invite
Your frontend application can send the uuid
and token
from this link to the Reset password with link credentials endpoint or use them with the Userfront.resetPassword() method.
When using options.type="reset"
, the link will expire in 1 hour by default, instead of 3 days for a standard welcome email. See options.duration
to use a different value.
options.duration
Set the link duration with a number followed by seconds, minutes, hours, days, or weeks.
"30 seconds"
, "1 minute"
, "6 hours"
, "2 days"
, "1 week"
The duration must be between 10 seconds and 1 week. Default durations are:
options.type | Default duration |
---|---|
welcome (default) | 3 days |
reset | 1 hour |
#Create or update user
Create a user or, if the user already exists, update it.
Must include an email address if creating a user.
Must include a userId
or userUuid
if updating a user.
Payload parameters
The user's ID. Must include userId or userUuid.
The user's UUID. Must include userId or userUuid.
The user's email address. Required if creating a user.
Phone number in E.164 format.
The user's username. If not provided, one is created automatically.
The user's first and last name.
The user's profile image URL.
When set to true, the user will not be able to log in or obtain new access tokens.
A flexible JSON object for saving additional user data.
When set to true, the user must log in with MFA.
The factor preferred by the user for their first login step.
The factor preferred by the user for their second login step.
The user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
#Mark user active
Mark a user as active. This updates a user's lastActiveAt
timestamp to the
current time.
Payload parameters
#Tenants
Tenants allow you to sub-divide your application so that certain users only have access to certain parts.
For example, your workspace could have Tenant A and Tenant B. You could give some users access to Tenant A, some users access to Tenant B, some users access to both Tenants, and some users access to neither Tenant.
You can create and read tenants with standard REST operations.
#Create tenant
Creates a new tenant.
#Create child tenant
Creates a new tenant as a child of the specified tenant.
This endpoint behaves the same as Create tenant, but creates the new tenant as a child of the tenant specified in the URL.
The API key used with this endpoint can belong to the tenant specified in the URL, or to its parent or grandparent tenant.
#Read tenant
Reads a tenant record by its tenantId
.
Payload parameters
#Update tenant
Updates an existing tenant.
#Delete tenant
Deletes an existing tenant.
Payload parameters
#Search tenants
Search tenant records within a parent tenant. Responses contain 24 results per page.
Payload parameters
The order in which to return the results. Can be ascending or descending for the following: lastActiveAt (default), createdAt, updatedAt, or name. For example: createdAt_ASC or name_DESC.
The page number of results to return.
A filter object for returning tenant results.
#Filter options
The filters
object has a top-level conjunction
that applies to one or more filterGroups
.
The "and"
conjunction returns results that meet all of the criteria, while the "or"
conjunction returns results that meet any one of the criteria.
Each filter
has the following options:
#attr
The attribute to search, such as name
, tenantId
, or uuid
. For attributes in the data
object, use data.myAttr
.
#type
The data type of the attribute. Can be string
, boolean
, number
, date
, or array
.
#comparison
The desired criteria for returned results.
Type | Comparisons |
---|---|
string | is contains does not contain starts with ends with is unknown has any value |
boolean | is is not |
date | before after between less than (days ago)more than (days ago) |
number | is more than less than |
array | contains does not contain any |
#value
The value to be compared. Should make sense in the context of the type
and comparison
.
#Example searches
Tenants with Acme in the name
Tenants matching 2 custom data attributes
#Roles
Roles are used to apply access control for users within your application and can be used application-wide or to specific Tenants within your application.
You can restrict or allow a user's access by assigning one or more roles to the user and verifying their role provided in the JWT access token.
You can create, read, and delete roles with standard REST operations.
- Dashboard: JWT access tokens
- Docs: Tokens and access control - Access control
#Create role
Create a new role.
The name for your role can include different casing, numbers, and special characters.
Examples
ResourceOwner
tier-3
dev_access-write 1
Payload parameters
Role name. Cannot begin or end with whitespace.
#List roles
Lists all the roles available in your application.
Payload parameters
#Set user roles
Sets the roles for a given user.
The role(s) set with this route will be at the application-wide level. To set a user's role(s) within a specific tenant, see Set user roles (tenant level).
To remove all roles for a user, pass an empty array for roles
.
Payload parameters
An array of roles to assign to the user. To remove all roles for a user, pass an empty array `{ roles: [] }`
#Invite user to a role
Invite a user to join the application with the given role(s).
This endpoint creates a user, then sends them an email with a link to log in (default) or set their password (see options.type).
The role(s) that is created will be at the application-wide level. To invite a user to a role within a specific tenant, see Invite user to a role (tenant level).
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
The user's email address.
The user's first and last name.
An array of roles to assign to the user.
Options object.
The type of link to send in the invitation email.
The length of time before the invitation link expires.
If true, no invitation email will be sent.
options.type
reset
Use options.type = "reset"
to send the invitation email with a link to your Password Reset Path. For example:
/reset?uuid=...&token=...&type=invite
Your frontend application can send the uuid
and token
from this link to the Reset password with link credentials endpoint or use them with the Userfront.resetPassword() method.
When using options.type="reset"
, the link will expire in 1 hour by default, instead of 3 days for a standard welcome email. See options.duration
to use a different value.
options.duration
Set the link duration with a number followed by seconds, minutes, hours, days, or weeks.
"30 seconds"
, "1 minute"
, "6 hours"
, "2 days"
, "1 week"
The duration must be between 10 seconds and 1 week. Default durations are:
options.type | Default duration |
---|---|
welcome (default) | 3 days |
reset | 1 hour |
#Delete role
Delete an existing role.
A role cannot be deleted if it is assigned to users.
Payload parameters
#Create role (tenant level)
Create a role for the specified tenant.
The name for your role can include different casing, numbers, and special characters.
Examples
ResourceOwner
tier-3
dev_access-write 1
Payload parameters
Role name. Cannot begin or end with whitespace.
#List roles (tenant level)
Lists all the roles available within the specified tenant.
Payload parameters
#Set user roles (tenant level)
Sets the roles for a given user within the specified tenant.
To remove all roles for a user within the specified tenant, pass an empty array for roles
.
Payload parameters
An array of roles to assign to the user. To remove all roles for a user, pass an empty array `{ roles: [] }`
#Invite user to a role (tenant level)
Invite a user to join the application with the given role(s) in the specified tenant.
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
The user's email address.
The user's first and last name.
An array of roles to assign to the user.
Options object.
The type of link to send in the invitation email.
The length of time before the invitation link expires.
If true, no invitation email will be sent.
options.type
reset
Use options.type = "reset"
to send the invitation email with a link to your Password Reset Path. For example:
/reset?uuid=...&token=...&type=invite
Your frontend application can send the uuid
and token
from this link to the Reset password with link credentials endpoint or use them with the Userfront.resetPassword() method.
When using options.type="reset"
, the link will expire in 1 hour by default, instead of 3 days for a standard welcome email. See options.duration
to use a different value.
options.duration
Set the link duration with a number followed by seconds, minutes, hours, days, or weeks.
"30 seconds"
, "1 minute"
, "6 hours"
, "2 days"
, "1 week"
The duration must be between 10 seconds and 1 week. Default durations are:
options.type | Default duration |
---|---|
welcome (default) | 3 days |
reset | 1 hour |
#Delete role (tenant level)
Delete an existing role in the specified tenant.
A role cannot be deleted if it is assigned to a user.
Payload parameters
#User Imports
Userfront allows you to import users that you already have in your own database.
Use the Create user import endpoint with a list of JSON-formatted users to import users.
You can create, read, and delete user imports with standard REST operations.
To import users with a CSV in the dashboard, see Import users.
#Create user import
Creates a user import that will remain idle until it is processed.
See Process user import to import the users and for an example of users after processing,
Payload parameters
#User attributes
All user objects in the request payload must contain the following attributes:
email
The following attributes are converted to lowercase when the user import is processed:
email
username
Attributes not specified below will be stored in user.data
for your use (e.g. user.data.customAttr
)
- See how users are represented after processing in Process user import.
Importing live mode user passwords:
- Import your users without
password
defined. - Use the Passthrough migration to transfer user passwords from your production server. Your users will be able to log in without disruption (e.g. requiring a password reset).
Importing test mode user passwords:
- If
password
is defined, it will be encrypted before being stored and the user will be able to log in with the password provided after the user import is processed. This is intended for test mode use only as an alternative to Passthrough migration. - Password must be at least 16 characters OR at least 8 characters including a number and a letter.
- All other attributes named
Password
orpassword
are not saved to the user record for security. - Contact sales if importing sensitive information is a requirement for your organization.
Attribute | Type | Description |
---|---|---|
id or userId | number | User identifier. |
uuid or userUuid | uuid | Unique user identifier. |
email | string | User's email. |
phoneNumber | string | Phone number in E.164 format. |
username | string | User's username. |
name | string | User's first and last name. |
image | string | User's profile image URL. |
locked | boolean | If set to true, the user will not be able to log in or obtain new access tokens. |
password | string | User's password. |
isMfaRequired | boolean | If set to true, the user must log in with MFA. |
isEmailConfirmed | boolean | Whether the user's email is confirmed. |
isPhoneNumberConfirmed | boolean | Whether the user's phone number is confirmed. |
#Process user import
Begins the process of importing users from the user import specified by importUuid
.
Use the Read user import endpoint to check the status.
A user import with a null completedAt
attribute means it has not been processed yet.
The user import is processed with the following behavior:
id
or userId
:
- Will be saved to
user.userId
- If both
id
anduserId
are present:userId
is given precedence and saved touser.userId
id
will be saved touser.data.id
.
uuid
or userUuid
:
- Will be saved to
user.userUuid
- If both
uuid
anduserUuid
are present:userUuid
is given precedence and saved touser.userUuid
uuid
will be saved touser.data.uuid
.
Payload parameters
End result User objects
#List user imports
Lists all user import records.
Payload parameters
#User import states
Unprocessed user import
Processed user import (all successes)
Processed user import (some failures)
#Read user import
Read a user import record by its importUuid
.
Payload parameters
#Delete user import
Deletes a user import record by importUuid
.
The users defined in the user import will not be deleted if the user import has already been processed.
Payload parameters
#API Keys
API keys are a way to authenticate machine-to-machine requests, either from your server to Userfront, or from your users' servers to your server.
You can create, read, invalidate, delete, and verify API keys with standard REST operations.
#Create API key
Create a new API key with a given type.
Payload parameters
The type of API key ("admin", "readonly", "webhook")
Type | Description |
---|---|
admin | Allows all Userfront actions for a tenant |
readonly | Allows readonly actions for a tenant |
webhook | Included in webhook headers sent by Userfront |
#List API keys
Lists all of a tenant's API keys for a given type.
Type | Description |
---|---|
admin | Allows all Userfront actions for a tenant |
readonly | Allows readonly actions for a tenant |
webhook | Included in webhook headers sent by Userfront |
Payload parameters
#Verify API key
Verify that an API key is valid.
Include your admin API key in the authorization
header, and include the key that you want to verify as key
in the request body.
An API key cannot be used to verify itself.
Payload parameters
The API key to verify
#Invalid API key
When an API key is invalid, Userfront returns a 400 status code response with the message "Invalid API key".
#Invalidate API key
Invalidate an API key.
API keys that have been invalidated are still returned in the list API keys response, but have the isActive
value set to false
.
API keys that have been invalidated will return 400 "Invalid" for verify API key.
Payload parameters
The API key to invalidate
You cannot invalidate the final API key of a given type. You must create another key to take its place before invalidating.
#Delete API key
Delete an API key.
API keys that have been deleted will return 400 "Invalid" for verify API key.
Payload parameters
The API key to delete
You cannot delete the final API key of a given type. You must create another key to take its place before deleting.
#List API keys (tenant level)
Lists all of a tenant's API keys for a given type.
Type | Description |
---|---|
admin | Allows all Userfront actions for a tenant |
readonly | Allows readonly actions for a tenant |
webhook | Included in webhook headers sent by Userfront |
Payload parameters
#JWTs
Userfront issues a JWT access token to each user when they log into your application.
Your client (frontend) application should send the JWT access token to your server with each request, where you can verify it using your JWT public key.
Your JWT public key(s) can be viewed directly with the /v0/tenants/:tenantId/keys/jwt
endpoint, or as a JSON Web Key Set (JWKS) with the /v0/tenants/:tenantId/jwks
endpoint.
For more information about JWT access tokens, see Concepts › JWT Access Tokens › Using JWTs.
#List JWT public keys
Lists all of a tenant's JWT public keys in both plaintext (publicKey
) and Base64 (publicKeyBase64
) format.
#Query strings
Optional query string for test mode (?test=true)
#JSON Web Key Set
The public JWKS url for a tenant.
A JSON Web Key Set allows your application to build your JWT public key(s) from a URL instead of hard-coding the latest JWT public key into your code.
The JWKS representation requires fewer bytes than a full JWT public key, which is preferable if you want your application to look up public key information in realtime instead of hard-coding a JWT public key.
When you set up your application to use JWKS instead of a hard-coded JWT public key, you can rotate your JWT signing key without having to update your application code.
#Query strings
Optional query string for test mode (?test=true)
Payload parameters
#Create custom JWT access token
Create a JWT access token with a custom payload.
If proper userId
and authorization
are included, this token is usable against the Userfront API.
Custom JWT access tokens are in beta, and token refresh for custom JWT access tokens has not yet been released.
Payload parameters
The object to use as the JWT access token payload. Cannot include "tenantId", "sessionId", "mode", "exp", or "iat" as attributes.
Unique numerical identifier for the user. For use with options.userAttributes.
Universal unique identifier (UUID) for the user. For use with options.userAttributes.
Options object.
Array of user attribute names. When userId or userUuid is present, looks up the provided attributes for the user and adds them to the JWT access token payload.
The length of time before the JWT access token expires, in words like "1 hour". Accepts singular and plural of "seconds", "minutes", "hours", "days", "weeks", "months", and "years".
The length of time before the refresh token expires, in words like "1 week". Accepts singular and plural of "seconds", "minutes", "hours", "days", "weeks", "months", and "years".
#Example JWT access tokens
Custom JWT access token
Given the following request body:
The resulting JWT access token payload will be:
JWT access token with userId
in payload
Given the following request body:
The resulting JWT access token payload will be:
JWT access token with options.userAttributes
Given the following request body:
The resulting JWT access token payload will be:
#Token duration
For options.accessTokenDuration
and options.refreshTokenDuration
, use a number and word like "30 seconds"
, "1 minute"
, "6 hours"
, "2 days"
, "1 week"
If only one duration is set (e.g. only options.accessTokenDuration
), the other duration is also set to that value.
When not set, these durations default to the tenant's token durations.
#Authentication actions
Server-to-server authentication actions allow your backend to perform actions that an end user cannot perform on their own, such as directly generating login link credentials.
#Generate link credentials
Generate link credentials for use in custom login, welcome, verification, or password reset flows.
This endpoint returns the uuid
and token
credentials but does not send an email.
The generated uuid
and token
combination can only be used once.
If you want Userfront to send an email on your behalf, you can use endpoints like generate login link or generate password reset link.
Payload parameters
The user's email address. Must be present if userId is not present.
Unique numerical identifier for the user. Must be present if email is not present.
Options object.
The type of link to generate.
The length of time before the link expires.
options.type
options.type | Default expiration |
---|---|
login (default) | 1 hour |
welcome | 3 days |
verify | 3 days |
reset | 1 hour |
#Login, welcome, and verify
Your frontend application can send the generated uuid
and token
to the Log in with login link endpoint or use them with the Userfront.login() method.
#Password reset
Your frontend application can send the generated uuid
and token
to the Reset password with link credentials endpoint or use them with the Userfront.resetPassword() method.
options.duration
Set the link duration with a number followed by seconds, minutes, hours, days, or weeks.
"30 seconds"
, "1 minute"
, "6 hours"
, "2 days"
, "1 week"
The duration must be between 10 seconds and 1 week. Default durations are:
options.type | Default duration |
---|---|
login (default) | 1 hour |
welcome | 3 days |
verify | 3 days |
reset | 1 hour |