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.
#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 API key you use to authenticate the request determines whether the request is live mode or test mode.
https://api.userfront.com
#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(opens new window). 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 | 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.) |
#Users
Users are the user records within your account or within your account'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 import & export.
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
#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.
Parameters
Unique 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.
#Delete user
#Search users
Search users within a tenant. Responses contain 24 results per page.
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).
Parameters
Unique 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 user's password. Password must be at least 16 characters OR at least 8 characters including a number and a letter.
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.
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 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.
Parameters
#Tenants
Tenants allow you to sub-divide your application so that certain users only have access to certain parts.
For example, your account 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
.
Parameters
#Update tenant
Updates an existing tenant.
#Delete tenant
#Search tenants
Search tenant records within a parent tenant. Responses contain 24 results per page.
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
or tenantId
. 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 labels you can use to determine each user's access control within your application.
You can assign one or more roles to each user, and roles can apply to your entire application or to tenants within your application.
You can create, read, update, and delete roles with standard REST operations.
#List roles
Lists all the roles available in your account.
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
.
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).
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.
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 |
#List roles (tenant level)
Lists all the roles available within the specified tenant.
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
.
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.
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.
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 |
#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.
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 |
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.
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.
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.
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 |
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 Tokens and access control.
#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(opens new window) 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)
Parameters
#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.
Parameters
The user's email address. Must be present if userId is not present.
The user's ID. 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 |