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.

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.

API keys are secrets used to authenticate requests. View and manage your admin and read-only API keys at Dashboard › Authentication › API keys.

Test mode keys have the prefix uf_test_ and live mode keys have the prefix uf_live_.

API keys carry many privileges, so keep them safe and secure! Do not share or expose API keys in publicly accessible areas such as repositories, client-side code, and so forth.

Authentication to the API is made using the Bearer Auth header. Provide your API key in the header of each request as: Authorization: Bearer uf_api_key.

A secure connection served over HTTPS with valid authentication is required for all API requests.

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.

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 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.

Creates a new user.

Read a user record by its userId.

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.

Deletes a user record.

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

#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

#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".

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).

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.

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

Read a user's sessions.

Log out a user and invalidate all of their sessions or invalidate a specific session.

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.

Creates a new 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.

Reads a tenant record by its tenantId.

Updates an existing tenant.

Deletes an existing tenant, its descendants, its roles, and removes user access to the tenant. Users with roles in the tenant will not be deleted but their roles will be removed.

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

#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. Only valid attributes are name, tenantId, data, aliasId, 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.

#value

The value to be compared. Should make sense in the context of the type and comparison.

#Example searches

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.

Create a new role.

Lists all the roles available in your application.

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.

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).

Delete an existing role.

Create a role for the specified tenant.

Lists all the roles available within the specified tenant.

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.

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

Delete an existing role in the specified tenant.

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.

Creates a user import that will remain idle until it is processed.

#User attributes

Begins the process of importing users from the user import specified by importUuid. Use the Read user import endpoint to check the status.

The user import is processed with the following behavior:

id or userId:

• Will be saved to user.userId
• If both id and userId are present:
  • userId is given precedence and saved to user.userId
  • id will be saved to user.data.id.

uuid or userUuid:

• Will be saved to user.userUuid
• If both uuid and userUuid are present:
  • userUuid is given precedence and saved to user.userUuid
  • uuid will be saved to user.data.uuid.

Lists all user import records.

#User import states

Read a user import record by its importUuid.

Deletes a user import record by importUuid.

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 a new API key with a given type.

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

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.

#Invalid API key

When an API key is invalid, Userfront returns a 400 status code response with the message "Invalid 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.

Delete an API key.

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

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

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.

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

#Query strings

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

Create a JWT access token with a custom payload.

If proper userId and authorization are included, this token is usable against the Userfront API.

#Example JWT access tokens

#Token duration

For options.accessTokenDuration and options.refreshTokenDuration, use a number and word like "30 seconds", "1 minute", "6 hours", "2 days", "1 week" , "1 month".

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.

Create or update the JWT access token format to be issued to users when they log in.

If proper userId and authorization are included, this token is usable against the Userfront API.

Read the format of a tenant's JWT access token. An object of claims is returned with each claim having a type and source.

The type is "required", "optional", "OIDC", or "custom".

Read the Userfront-defined claims available to be added to a tenant's JWT access token. An object of claims is returned with each claim having a type and source.

The type is "optional" or "OIDC".

The list is not exhaustive, "custom" claims can be added to the JWT format in addition to those returned here.

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 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.

#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.