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

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.

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.

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.

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.

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.

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.

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

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.

Lists all the roles available in your account.

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

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.

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.

For more information about JWT access tokens, see Tokens and access control.

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

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.