# API reference

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.

# Just getting started?

Check out our development quickstart guide.

# Base URL

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.

# Your API Key

uf_test_readonly_demo1234_2d87b3d230bda5685276b43efdac2852

Your test API key is included in all the examples here, so you can test the code samples right away.

In general, you should include your API key in the header of requests:

{
  headers: {
    authorization: "Bearer uf_test_readonly_demo1234_2d87b3d230bda5685276b43efdac2852"
  }
}

A sample test API key is included in all the examples here, so you can test any example right away.

To test requests using your account, replace the sample API key with your actual API key or sign in.

Sign in

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

# HTTP Status Code Summary

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.

TIP

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

Parameters


No parameters

Response

{}

# Read user

Reads a user record by its userId.

Parameters


No parameters

Response

{}

# 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


No parameters

Response

{}

# Delete user

Deletes a user record.

Parameters


No parameters

Response

{}

# Search users

Search user records.

Parameters


No parameters

Response

{}

# Invite user

Invite a user by email address.

Parameters


No parameters

Response

{}

# Create or update user

Create a user or, if the user already exists, update it.

Parameters


No parameters

Response

{}

# Mark user active

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

Parameters


No parameters

Response

{}

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

Parameters


No parameters

Response

{}

# Read tenant

Reads a tenant record by its tenantId.

Parameters


No parameters

Response

{}

# Update tenant

Updates an existing tenant.

Parameters


No parameters

Response

{}

# Delete tenant

Deletes an existing tenant.

Parameters


No parameters

Response

{}

# 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


No parameters

Response

{}

# 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


No parameters

Response

{}

# Invite user to a role

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

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


No parameters

Response

{}

# 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


No parameters

Response

{}

# Invite user to a role (tenant level)

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

Parameters


No parameters

Response

{}

Last Updated: 9/22/2021, 5:44:45 PM