# API reference

Client-to-server

👩‍💻

This documentation covers requests made by a user's browser or mobile app directly to Userfront's server.

For requests made by your server to Userfront's server using your application's API key, see the API reference for server-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 request origin and JWT access token used to for the request determine whether the request is live mode or test mode.

# Base URL

https://api.userfront.com

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

# Error response format

Errors contain a statusCode, message, and error object.

The message describes what went wrong for the request, while the error object contains additional information about the error.

Error response

{
  "statusCode": 400,
  "message": "Incorrect email or password",
  "error": {
    "type": "bad_request_error"
  }
}

# Authentication actions

Authentication actions allow a user to sign up, log in, perform password resets, and carry out other useful interactions with your application.

Most of these actions are also implemented with helper functions in the Core JS library.


# Sign up with password

Register a new user with an email and password.

Parameters


No parameters

# Welcome / signup email

By default, Userfront sends new users a welcome email to confirm their account. The link in this email contains a uuid and token that allow login the same way as a login link.

You can disable this email with the options.noSignupEmail parameter above.

In test mode, Userfront does not send emails.

Response

{}

# Alternate response: MFA - First factor code

Response when tenant requires MFA.

See Multi-factor authentication - First factor code for more information on how to request & submit a verification code using the information in this response.

Response (MFA - First factor code)

{
  "message": "OK",
  "result": {
    "mode": "live",
    "firstFactorCode": "304a8def-651c-4ab2-9ca0-1e3fca9e280a",
    "allowedStrategies": [
      "verificationCode"
    ],
    "allowedChannels": [
      "sms"
    ]
  }
}

# Sign up with passwordless

Register a new user with an email, and send them a login link email.

If the user already exists, sends them a login link email. See send login link email.

Parameters


No parameters

Response

{}

# Test mode

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

Response (test mode)

{
  "message": "OK",
  "result": {
    "link": "http://localhost:3000/login?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e&type=welcome"
  }
}

# Welcome / signup email

By default, Userfront sends new users a welcome email to confirm their account. The link in this email contains a uuid and token and works the same way as a login link.

You can disable this email with the options.noSignupEmail parameter above.

Response (options.noSignupEmail: true)

{
  "message": "OK"
}

# Log in with password

Log in with a password and email/username.

Parameters


No parameters

Response

{}

# Password reset email

By default, Userfront sends a password reset link email to users when they try to log in with a password but have not yet set a password.

You can disable this email with the options.noResetEmail parameter, which will then return an error of the type "intended_error". This distinguishes the request from a user who has a password; their error would be "bad_request_error"

Response (options.noResetEmail: true)

{
  "statusCode": 400,
  "message": "Incorrect email or password",
  "error": {
    "type": "intended_error"
  }
}

# Alternate response: MFA - First factor code

Response when tenant requires MFA.

See Multi-factor authentication - First factor code for more information on how to request & submit a verification code using the information in this response.

Response (MFA - First factor code)

{
  "message": "OK",
  "result": {
    "mode": "live",
    "firstFactorCode": "304a8def-651c-4ab2-9ca0-1e3fca9e280a",
    "allowedStrategies": [
      "verificationCode"
    ],
    "allowedChannels": [
      "sms"
    ]
  }
}

# Update own password

Update a user's password using their valid JWT access token and their existing password.

The request must include a valid JWT access token in the Authorization header.

Parameters


No parameters

Response

{
  "message": "OK"
}

# If no password exists

If the user does not have a password (for example, if they logged in via SSO), the password and existingPassword fields are both ignored, and Userfront sends the user a password reset link.

Response (if no password exists)

{
  "message": "OK",
  "result": {
    "to": "user@example.com",
    "messageId": "18299324-bf92-4ec9-bd47-403eda5f278d",
    "submittedAt": "2022-05-17T00:01:23.630Z"
  }
}

# Test mode

In test mode, Userfront does not send emails.

If a test user does not have a password, the API response will contain a link attribute that can be followed directly in order to set the password.

This link will direct the user to your Password reset path.

Response (if no password exists, test mode)

{
  "message": "OK",
  "result": {
    "link": "http://localhost:3000/reset?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e"
  }
}

# Update own email address

To update a user's own email address, send the new email address to the send account verification email endpoint.

This will generate a link the user can click to verify their new email address. They will retain their old email address until the link is clicked.




Generate and send a login link email.

Note

If no user exists with the given email, this endpoint creates a new user and sends them a login link.

See also: sign up with passwordless.

Parameters


No parameters

Response

{}

# Test mode

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

Response (test mode)

{
  "message": "OK",
  "result": {
    "link": "http://localhost:3000/login?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e&type=login"
  }
}

You can generate login link credentials to use in your own custom emails by using the generate link credentials endpoint.


Log in using the token and uuid from a login link.

Parameters


No parameters

Response

{}

# Alternate response: MFA - First factor code

Response when tenant requires MFA.

See Multi-factor authentication - First factor code for more information on how to request & submit a verification code using the information in this response.

Response (MFA - First factor code)

{
  "message": "OK",
  "result": {
    "mode": "live",
    "firstFactorCode": "304a8def-651c-4ab2-9ca0-1e3fca9e280a",
    "allowedStrategies": [
      "verificationCode"
    ],
    "allowedChannels": [
      "sms"
    ]
  }
}

# Log in with SSO

Log in using an SSO provider by visiting a link for that provider.

The SSO provider must already be configured.

# Provider

The :provider value should be the lowercased name of the SSO provider.

Example: github

# Query strings


# tenant_id  required

Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.


# origin  required

The origin of the requesting page.


# redirect  optional

A path to redirect the user to upon sign on.





# Refresh JWT access token

Send a user's valid refresh token to obtain a new JWT access token.

The request must include a valid refresh token in the Authorization header.

Parameters


No parameters

Response

{}


# Send password reset email

Generate and send a password reset link email.

Parameters


No parameters

Response

{}

# Test mode

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to reset the user's password.

Response (test mode)

{
  "message": "OK",
  "result": {
    "link": "http://localhost:3000/reset?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e"
  }
}

You can generate password reset link credentials to use in your own custom emails by using the generate link credentials endpoint.


Reset a user's password using the token and uuid from a password reset link.

Upon success, returns a JWT access token so that the user can log in directly.

Parameters


No parameters

Response

{}

# Alternate response: MFA - First factor code

Response when tenant requires MFA.

See Multi-factor authentication - First factor code for more information on how to request & submit a verification code using the information in this response.

Response (MFA - First factor code)

{
  "message": "OK",
  "result": {
    "mode": "live",
    "firstFactorCode": "304a8def-651c-4ab2-9ca0-1e3fca9e280a",
    "allowedStrategies": [
      "verificationCode"
    ],
    "allowedChannels": [
      "sms"
    ]
  }
}

# Send account verification email

Generate and send an account verification link email.

After a user follows the account verification link, their user record is marked isConfirmed: true.

If the user submitted a new email address to this endpoint, their email address is updated when they follow the account verification link.

You can process the account verification link's token and uuid credentials the same way as login link credentials: with Log in with login link.

Parameters


No parameters

Response

{}

# Test mode

In test mode, Userfront does not send emails. Instead, the API response will contain a link attribute that can be followed directly to log in.

Response (test mode)

{
  "message": "OK",
  "result": {
    "link": "http://localhost:3000/login?uuid=64758625-a004-44d0-90fe-fa7e5b012be4&token=d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e&type=verify"
  }
}

You can generate account verification link credentials to use in your own custom emails by using the generate link credentials endpoint.

# Log out

Log a user out and invalidate their current session.

In order to invalidate the user's current session, the request must include a valid JWT access token or refresh token in the Authorization header. This token can be expired.

Parameters


No parameters

Response

{}

# Multi-factor authentication

When Multi-factor authentication (MFA) is enabled, a user's initial login request will return a firstFactorCode instead of their JWT access token.

This firstFactorCode can then be sent along with a second factor in order to obtain the JWT access token.

Note

MFA is currently in beta. If you would like to enable it for your account, please contact us using the chat in the bottom-right.

# First factor code

The response to the right is returned when using one of the following methods when MFA is enabled for your tenant:

The response contains a firstFactorCode, strategies, and channels to use in order to Send verification code (SMS) and Login with verification code via the MFA endpoints.

Response (MFA - First factor code)

{
  "message": "OK",
  "result": {
    "mode": "live",
    "firstFactorCode": "304a8def-651c-4ab2-9ca0-1e3fca9e280a",
    "allowedStrategies": [
      "verificationCode"
    ],
    "allowedChannels": [
      "sms"
    ]
  }
}

# Send verification code (SMS)

Send a verification code via SMS to complete login process.

After this request is made, you can perform a Login with verification code using the verification code sent to the user.

Parameters


No parameters
  • strategy is one of allowedStrategies found in the first factor code response.

  • channel is one of allowedChannels found in the first factor code response.

  • to phone number must be in E.164 format.

    E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits. e.g. +15558675309

Response

{}

# Login with verification code

Log a user in using a verification code to complete the login process.

Parameters


No parameters
  • strategy is one of allowedStrategies found in the first factor code response.

  • channel is one of allowedChannels found in the first factor code response.

  • to phone number must be in E.164 format.

    E.164 numbers are formatted [+] [country code] [subscriber number including area code] and can have a maximum of fifteen digits. e.g. +15558675309

Response

{}

# SAML

There are three endpoints to log users in and out using SAML.

View the SAML set up guide (opens new window) to set up your service provider in the Userfront dashboard. SAML is only available in live mode.


# Generate SAML token

Generate token to complete SAML login/logout.

You will need to obtain a SAML token with a valid JWT access token in the Authorization header. You will then use the token to complete the SAML flow using either of the endpoints below to log a user in or out:

  • GET /v0/auth/saml/idp/login
  • GET /v0/auth/saml/idp/logout

Parameters


No parameters

Response

{
  "token": "d889bf75-9ab7-4354-82f9-3a1d9c8d6e6e"
}

# Log in with SAML

Complete SAML login with token.

When a service provider requests your identity provider's Login URL, the Userfront API will redirect the client to your After-logout path (opens new window) where you will obtain a token using the user's JWT access token as specified in Generate SAML token.

The response is a self-submitting form containing the SAML response which sends a POST request to the service provider to complete the login process.

# Parameters


# tenant_id  required

Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.


# token  required

Generated SAML token.


# uuid  required

The user's UUID.



# Log out with SAML

Complete SAML logout with token.

When a service provider requests your identity provider's Logout URL, the Userfront API will redirect the client to your After-logout path (opens new window) where you will obtain a token using the user's JWT access token as specified in Generate SAML token.

The response is a self-submitting form containing the SAML response which sends a POST request to the service provider to complete the logout process.

# Parameters


# tenant_id  required

Unique identifier for the tenant. Note that this querystring uses underscore instead of camelcase.


# token  required

Generated SAML token.


# uuid  required

The user's UUID.



Last Updated: 5/16/2022, 11:12:23 PM