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.

ErrorDescription
200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
402 - Request FailedThe parameters were valid but the request failed.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500 - Server ErrorSomething 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

admin only

Creates a new user.

If you want to import or create many users, see user import & export.

Parameters

#email required

The user's email address.

#username 

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

#name 

The user's first and last name.

#image 

The user's profile image URL.

#data 

A flexible JSON object for saving additional user data.

#isMfaRequired 

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

#password 

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

post /v0/users

#Read user

admin or readonly

Read a user record by its userId.

Parameters

No parameters
get /v0/users/{userId}

#Update user

admin only

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

#userId 

Unique identifier for the user.

#email 

The user's email address.

#phoneNumber 

Phone number in E.164 format.

#username 

The user's username.

#name 

The user's first and last name.

#image 

The user's profile image URL.

#locked 

When set to true, the user will not be able to log in or obtain new access tokens.

#data 

A flexible JSON object for saving additional user data.

#password 

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

#isMfaRequired 

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

put /v0/users/{userId}

#Delete user

admin only

Deletes a user record.

Parameters

No parameters
delete /v0/users/{userId}

#Search users

admin or readonly

Search users within a tenant. Responses contain 24 results per page.

Parameters

#order 

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.

#page 

The page number of results to return.

#filters 

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.

#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")
post /v0/users/find

#Invite User

admin only

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

#userId 

Unique identifier for the user.

#email required

The user's email address.

#username 

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

#phoneNumber 

Phone number in E.164 format.

#name 

The user's first and last name.

#image 

The user's profile image URL.

#locked 

When set to true, the user will not be able to log in or obtain new access tokens.

#data 

A flexible JSON object for saving additional user data.

#isMfaRequired 

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

#password 

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

#options 

Options object.

#options.type 

The type of link to send in the invitation email.

#options.duration 

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.typeDefault duration
welcome (default)3 days
reset1 hour
post /v0/users/invite

#Create or update user

admin only

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

#userId 

The user's ID. Must include userId or userUuid.

#userUuid 

The user's UUID. Must include userId or userUuid.

#email 

The user's email address. Required if creating a user.

#phoneNumber 

Phone number in E.164 format.

#username 

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

#name 

The user's first and last name.

#image 

The user's profile image URL.

#locked 

When set to true, the user will not be able to log in or obtain new access tokens.

#data 

A flexible JSON object for saving additional user data.

#isMfaRequired 

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

#password 

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

post /v0/users/createOrUpdate

#Mark user active

admin only

Mark a user as active. This updates a user's lastActiveAt timestamp to the current time.

Parameters

No parameters
post /v0/users/{userId}/active

#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

admin only

Creates a new tenant.

Parameters

#name 

The name of the tenant, which is displayed in the dashboard.

#image 

A URL for the tenant's image.

#data 

A flexible JSON object for saving additional tenant data.

post /v0/tenants

#Create child tenant

admin only

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.

Parameters

#name 

The name of the tenant, which is displayed in the dashboard.

#image 

A URL for the tenant's image.

#data 

A flexible JSON object for saving additional tenant data.

post /v0/tenants/{tenantId}/tenants

#Read tenant

admin or readonly

Reads a tenant record by its tenantId.

Parameters

No parameters
get /v0/tenants/{tenantId}

#Update tenant

admin only

Updates an existing tenant.

Parameters

#name 

The name of the tenant, which is displayed in the dashboard.

#image 

A URL for the tenant's image.

#data 

A flexible JSON object for saving additional tenant data.

put /v0/tenants/{tenantId}

#Delete tenant

admin only

Deletes an existing tenant.

Parameters

No parameters
delete /v0/tenants/{tenantId}

#Search tenants

admin or readonly

Search tenant records within a parent tenant. Responses contain 24 results per page.

Parameters

#order 

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.

#page 

The page number of results to return.

#filters 

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.

#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
post /v0/tenants/{tenantId}/tenants/find

#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

admin or readonly

Lists all the roles available in your account.

Parameters

No parameters
get /v0/roles

#Set user roles

admin only

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

#roles 

An array of roles to assign to the user. To remove all roles for a user, pass an empty array `{ roles: [] }`

put /v0/users/{userId}/roles

#Invite user to a role

admin only

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

#email required

The user's email address.

#name 

The user's first and last name.

#roles required

An array of roles to assign to the user.

#options 

Options object.

#options.type 

The type of link to send in the invitation email.

#options.duration 

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.typeDefault duration
welcome (default)3 days
reset1 hour
post /v0/roles/invite

#List roles (tenant level)

admin or readonly

Lists all the roles available within the specified tenant.

Parameters

No parameters
get /v0/tenants/{tenantId}/roles

#Set user roles (tenant level)

admin only

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

#roles 

An array of roles to assign to the user. To remove all roles for a user, pass an empty array `{ roles: [] }`

put /v0/tenants/{tenantId}/users/{userId}/roles

#Invite user to a role (tenant level)

admin only

Invite a user to join the application with the given role(s) in the specified tenant.

Parameters

#email required

The user's email address.

#name 

The user's first and last name.

#roles required

An array of roles to assign to the user.

#options 

Options object.

#options.type 

The type of link to send in the invitation email.

#options.duration 

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.typeDefault duration
welcome (default)3 days
reset1 hour
post /v0/tenants/{tenantId}/roles/invite

#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

admin only

Create a new API key with a given type.

Parameters

#type required

The type of API key ("admin", "readonly", "webhook")

typedescription
adminAllows all Userfront actions for a tenant
readonlyAllows readonly actions for a tenant
webhookIncluded in webhook headers sent by Userfront
post /v0/keys

#List API keys

admin only

Lists all of a tenant's API keys for a given type.

typedescription
adminAllows all Userfront actions for a tenant
readonlyAllows readonly actions for a tenant
webhookIncluded in webhook headers sent by Userfront

Parameters

No parameters
get /v0/keys/{type}

#Verify API key

admin only

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

#key required

The API key to verify

post /v0/keys/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

admin only

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

#key required

The API key to invalidate

put /v0/keys/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

admin only

Delete an API key.

API keys that have been deleted will return 400 "Invalid" for verify API key.

Parameters

#key required

The API key to delete

delete /v0/keys

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)

admin only

Lists all of a tenant's API keys for a given type.

typedescription
adminAllows all Userfront actions for a tenant
readonlyAllows readonly actions for a tenant
webhookIncluded in webhook headers sent by Userfront

Parameters

No parameters
get /v0/tenants/{tenantId}/keys/{type}

#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

public

Lists all of a tenant's JWT public keys in both plaintext (publicKey) and Base64 (publicKeyBase64) format.

#Query strings

test required

Optional query string for test mode (?test=true)

get /v0/tenants/{tenantId}/keys/jwt

#JSON Web Key Set

public

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

test required

Optional query string for test mode (?test=true)

Parameters

No parameters
get /v0/tenants/{tenantId}/jwks

#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

admin only

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

#email 

The user's email address. Must be present if userId is not present.

#userId 

The user's ID. Must be present if email is not present.

#options 

Options object.

#options.type 

The type of link to generate.

#options.duration 

The length of time before the link expires.

options.type
options.typeDefault expiration
login (default)1 hour
welcome3 days
verify3 days
reset1 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.typeDefault duration
login (default)1 hour
welcome3 days
verify3 days
reset1 hour
post /v0/auth/link/generate