# API reference

Server-to-server

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

# 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

# Filter options


The filters object has a top-level conjunction that applies to one or more filterGroups.

{
  "filters": {
    "conjunction": "and",
    "filterGroups": [
      {
        "conjunction": "and",
        "filters": [
          {
            "attr": "username",
            "type": "string",
            "comparison": "is",
            "value": "janedoe"
          }
        ]
      }
    ]
  }
}

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.

Comparison options
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
{
  "order": "createdAt_DESC",
  "filters": {
    "conjunction": "and",
    "filterGroups": [
      {
        "conjunction": "and",
        "filters": [
          {
            "attr": "createdAt",
            "type": "date",
            "comparison": "less than",
            "value": 7
          }
        ]
      }
    ]
  }
}
Users named John who were last active less than 30 days ago
{
  "filters": {
    "conjunction": "and",
    "filterGroups": [
      {
        "conjunction": "and",
        "filters": [
          {
            "attr": "name",
            "type": "string",
            "comparison": "contains",
            "value": "John"
          },
          {
            "attr": "lastActiveAt",
            "type": "date",
            "comparison": "less than",
            "value": 30
          }
        ]
      }
    ]
  }
}
Users with example.com in their email, or who have "Example" as a custom data attribute, sorted by username
{
  "order": "username_ASC",
  "filters": {
    "conjunction": "and",
    "filterGroups": [
      {
        "conjunction": "or",
        "filters": [
          {
            "attr": "email",
            "type": "string",
            "comparison": "ends with",
            "value": "@example.com"
          }
          {
            "attr": "data.projectName",
            "type": "string",
            "comparison": "is",
            "value": "Example"
          }
        ]
      }
    ]
  }
}

# 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")
{
  "filters": {
    "conjunction": "and",
    "filterGroups": [
      {
        "conjunction": "and",
        "filters": [
          {
            "attr": "role",
            "type": "string",
            "comparison": "is",
            "value": "demo1234:admin"
          }
        ]
      }
    ]
  }
}
Users with any role in the demo tenant (tenantId = "demo1234")
{
  "filters": {
    "conjunction": "and",
    "filterGroups": [
      {
        "conjunction": "and",
        "filters": [
          {
            "attr": "role",
            "type": "string",
            "comparison": "is",
            "value": "demo1234"
          }
        ]
      }
    ]
  }
}

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

{}

# List roles (tenant level)

Lists all the roles available within the specified tenant.

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

{}

# 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 for use in custom login, welcome, or verification flows.

This endpoint returns uuid and token link credentials but does not send an email.

The client application can use these link credentials in the Log in with login link endpoint or the Userfront.login() method.

If you want Userfront to send an email on your behalf, you can use endpoints like generate login link.

Parameters


No parameters

The link credentials can only be used once and will automatically expire according to the type of link:

options.type Expiration
login (default) 1 hour
welcome 3 days
verify 3 days

Response

{}
Last Updated: 11/6/2021, 12:05:20 AM