1. Overview

If you wish to utilize multiple tenants in FusionAuth, following this tutorial to get started.

2. Create a Tenant

To create a new tenant, navigate to Settings Tenants.

Create a Tenant
Table 1. Form Fields

Id Optional

An optional UUID. When this value is omitted a unique Id will be generated automatically.

Name Required

The name of the Tenant, this value is for display purposes only and may be changed after the tenant has been created.

3. Make an API call for a specific tenant

When more than one tenant exists, some APIs will require a tenant Id to ensure the request is not ambiguous.

There are two supported methods to provide the tenant Id to FusionAuth during the API request. The first is by using an HTTP header, and the other is using an API key that has been assigned to a specific tenant.

3.1. Using an HTTP Header

HTTP Header example

The following example demonstrates the HTTP Tenant header with an Id of 24b325e1-c1b8-4cc6-a2d3-ea316cec9e2e.

X-FusionAuth-TenantId: 24b325e1-c1b8-4cc6-a2d3-ea316cec9e2e

3.2. Using an API key

You may optionally create an API key that is scoped to a particular tenant. To create an API key navigate to Settings API Keys.

In the following example screenshot the tenant Pied Piper has been selected, this API key can be used to make API requests to FusionAuth instead of the HTTP header. Only Users, Groups and Applications belonging to the selected tenant will be visible to this API.

Create a Tenant API Key

3.3. Tenant Required Error

If you make an API request when the Tenant Id is required, you will receive a 400 response code with the following response body.

Tenant Required Error
  "generalErrors" : [ {
    "code" : "[TenantIdRequired]",
    "message" : "A Tenant Id is required to complete this request. To complete this request, you may assign a Tenant to your API key, or add the X-FusionAuth-TenantId HTTP request header with the Tenant Id."
  } ]