> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Tenant Manager API

Learn about the APIs for retrieving and updating Tenant Manager configuration.

# Tenant Manager API

This page contains the APIs used to retrieve and update Tenant Manager configuration.

version

Available since `1.65.0`

## Retrieve Tenant Manager Configuration

This API is used to retrieve the Tenant Manager configuration singleton.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Retrieve the Tenant Manager configuration

GET/api/tenant-manager

### Response

The response for this API contains the Tenant Manager configuration.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
| 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |

#### Response Body

`tenantManagerConfiguration.applicationConfigurations`Array<Object>

The list of universal applications that are enabled for Tenant Manager identity providers.

`tenantManagerConfiguration.applicationConfigurations[x].applicationId`UUID

The Id of a universal application enabled for Tenant Manager identity providers.

`tenantManagerConfiguration.attributeFormId`UUIDoptional

The Id of the registration form used to determine available attribute mapping targets.

`tenantManagerConfiguration.brandName`Stringoptional

The brand name displayed in Tenant Manager.

`tenantManagerConfiguration.identityProviderTypeConfigurations`Object

A map of tenant manager IdP type configurations keyed by Identity Provider type.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].defaultAttributeMappings`Map<String, String>

Default attribute mappings for this allowed Identity Provider type.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].enabled`Boolean

Whether this Identity Provider type is enabled for Tenant Manager.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this Identity Provider type configuration was created.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this Identity Provider type configuration was last updated.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategy`String

The linking strategy used for Identity Providers of this type.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].type`String

The identity provider type key for this configuration.

`tenantManagerConfiguration.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Tenant Manager configuration was created.

`tenantManagerConfiguration.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Tenant Manager configuration was last updated.

*Example JSON Response*

```json
{
  "tenantManagerConfiguration": {
    "attributeFormId": "a24e9397-16a4-4268-a0e0-4e31f5749b07",
    "applicationConfigurations": [
      {
        "applicationId": "9f5d3df4-2f65-4d2c-b851-6f58fdd7f8fd"
      }
    ],
    "brandName": "Acme Customer Portal",
    "identityProviderTypeConfigurations": {
      "OpenIDConnect": {
        "defaultAttributeMappings": {
          "registration.firstName": "given_name",
          "user.email": "email"
        },
        "enabled": true,
        "insertInstant": 1776789989231,
        "lastUpdateInstant": 1776790589231,
        "linkingStrategy": "LinkByEmail",
        "type": "OpenIDConnect"
      },
      "SAMLv2": {
        "defaultAttributeMappings": {},
        "enabled": false,
        "insertInstant": 1776789989231,
        "lastUpdateInstant": 1776790589231,
        "linkingStrategy": "LinkByUsername",
        "type": "SAMLv2"
      }
    },
    "insertInstant": 1776789989000,
    "lastUpdateInstant": 1776790589000
  }
}
```

## Update Tenant Manager Configuration

This API is used to update the Tenant Manager configuration.

No Id is required to update this object.

This API is used to update an existing Tenant Manager Configuration.

You must specify all of the properties of the Tenant Manager Configuration when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing Tenant Manager Configuration and your new data. It replaces the existing Tenant Manager Configuration with your new data.

Utilize the `PATCH` HTTP method to send specific changes to merge into an existing Tenant Manager Configuration.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Update the Tenant Manager configuration

PUT/api/tenant-manager

OpenAPI Spec

PATCH/api/tenant-manager

OpenAPI Spec

note

For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior:

*   [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json`
*   [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json`

For details, see the [PATCH documentation](https://fusionauth.io/docs/apis.md#the-patch-http-method).

Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list.

#### Request Body

`tenantManagerConfiguration.applicationConfigurations`Array<Object>optional

The list of universal applications enabled for Tenant Manager identity providers.

`tenantManagerConfiguration.applicationConfigurations[x].applicationId`UUIDoptional

The Id of a universal application enabled for Tenant Manager identity providers.

`tenantManagerConfiguration.attributeFormId`UUIDoptional

The Id of the registration form used to determine available attribute mapping targets.

`tenantManagerConfiguration.brandName`Stringoptional

The brand name displayed in Tenant Manager.

*Example Request JSON*

```json
{
  "tenantManagerConfiguration": {
    "applicationConfigurations": [
      {
        "applicationId": "9f5d3df4-2f65-4d2c-b851-6f58fdd7f8fd"
      }
    ],
    "attributeFormId": "a24e9397-16a4-4268-a0e0-4e31f5749b07",
    "brandName": "Acme Customer Portal"
  }
}
```

### Response

The response for this API contains the Tenant Manager configuration.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
| 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |

#### Response Body

`tenantManagerConfiguration.applicationConfigurations`Array<Object>

The list of universal applications that are enabled for Tenant Manager identity providers.

`tenantManagerConfiguration.applicationConfigurations[x].applicationId`UUID

The Id of a universal application enabled for Tenant Manager identity providers.

`tenantManagerConfiguration.attributeFormId`UUIDoptional

The Id of the registration form used to determine available attribute mapping targets.

`tenantManagerConfiguration.brandName`Stringoptional

The brand name displayed in Tenant Manager.

`tenantManagerConfiguration.identityProviderTypeConfigurations`Object

A map of tenant manager IdP type configurations keyed by Identity Provider type.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].defaultAttributeMappings`Map<String, String>

Default attribute mappings for this allowed Identity Provider type.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].enabled`Boolean

Whether this Identity Provider type is enabled for Tenant Manager.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this Identity Provider type configuration was created.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this Identity Provider type configuration was last updated.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategy`String

The linking strategy used for Identity Providers of this type.

`tenantManagerConfiguration.identityProviderTypeConfigurations[type].type`String

The identity provider type key for this configuration.

`tenantManagerConfiguration.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Tenant Manager configuration was created.

`tenantManagerConfiguration.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that the Tenant Manager configuration was last updated.

*Example JSON Response*

```json
{
  "tenantManagerConfiguration": {
    "attributeFormId": "a24e9397-16a4-4268-a0e0-4e31f5749b07",
    "applicationConfigurations": [
      {
        "applicationId": "9f5d3df4-2f65-4d2c-b851-6f58fdd7f8fd"
      }
    ],
    "brandName": "Acme Customer Portal",
    "identityProviderTypeConfigurations": {
      "OpenIDConnect": {
        "defaultAttributeMappings": {
          "registration.firstName": "given_name",
          "user.email": "email"
        },
        "enabled": true,
        "insertInstant": 1776789989231,
        "lastUpdateInstant": 1776790589231,
        "linkingStrategy": "LinkByEmail",
        "type": "OpenIDConnect"
      },
      "SAMLv2": {
        "defaultAttributeMappings": {},
        "enabled": false,
        "insertInstant": 1776789989231,
        "lastUpdateInstant": 1776790589231,
        "linkingStrategy": "LinkByUsername",
        "type": "SAMLv2"
      }
    },
    "insertInstant": 1776789989000,
    "lastUpdateInstant": 1776790589000
  }
}
```

## Tenant Manager Identity Provider Type Configuration APIs

The following APIs are used to manage Tenant Manager identity provider type configurations.

note

These APIs require a global API key. Requests made using a tenant-scoped API key, or requests containing the `X-FusionAuth-TenantId` request header, are forbidden.

### Create a Tenant Manager Identity Provider Type Configuration

This API is used to create a Tenant Manager identity provider type configuration.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Create a Tenant Manager identity provider type configuration

POST/api/tenant-manager/identity-provider/{type}

OpenAPI Spec

#### Request Parameters

`type`Stringrequired

The identity provider type key. Valid values are `OpenIDConnect` and `SAMLv2`.

#### Request Body

`typeConfiguration.defaultAttributeMappings`Map<String, String>optional

A map of default attribute mappings. Mapping keys not present in the configured Tenant Manager attribute form are removed before persistence.

`typeConfiguration.defaultAttributeMappings[key]`Stringoptional

The source expression used to populate the mapped FusionAuth user or registration field.

`typeConfiguration.enabled`BooleanoptionalDefaults to true

Whether this identity provider type is enabled for Tenant Manager.

`typeConfiguration.linkingStrategy`Stringoptional

The linking strategy for this identity provider type. Required when creating or replacing a type configuration. Valid values are `LinkByEmail`, `LinkByEmailForExistingUser`, `LinkByUsername`, and `LinkByUsernameForExistingUser`.

`typeConfiguration.type`Stringoptional

The identity provider type key. This value is read from the URI path parameter and any value provided in the request body is ignored.

*Example Request JSON*

```json
{
  "typeConfiguration": {
    "defaultAttributeMappings": {
      "registration.data.department": "department",
      "registration.username": "preferred_username",
      "user.email": "email",
      "user.firstName": "given_name"
    },
    "enabled": true,
    "linkingStrategy": "LinkByEmail"
  }
}
```

note

The `type` value is read from the URI path parameter. Any `typeConfiguration.type` value supplied in the request body is ignored.

note

Default attribute mapping keys are filtered against the configured Tenant Manager registration form. The `user.password` mapping key is always restricted and is not persisted.

### Response

The response for this API contains the created identity provider type configuration.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body

`typeConfiguration.defaultAttributeMappings`Map<String, String>

A map of default attribute mappings for this identity provider type.

`typeConfiguration.defaultAttributeMappings[key]`String

The source expression used to populate the mapped FusionAuth user or registration field.

`typeConfiguration.enabled`Boolean

Whether this identity provider type is enabled for Tenant Manager.

`typeConfiguration.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this identity provider type configuration was created.

`typeConfiguration.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this identity provider type configuration was last updated.

`typeConfiguration.linkingStrategy`String

The linking strategy for this identity provider type configuration.

`typeConfiguration.type`String

The identity provider type key for this configuration.

*Example JSON Response*

```json
{
  "typeConfiguration": {
    "defaultAttributeMappings": {
      "registration.data.department": "department",
      "registration.username": "preferred_username",
      "user.email": "email",
      "user.firstName": "given_name"
    },
    "enabled": true,
    "insertInstant": 1776791200111,
    "lastUpdateInstant": 1776791266333,
    "linkingStrategy": "LinkByEmail",
    "type": "OpenIDConnect"
  }
}
```

### Update a Tenant Manager Identity Provider Type Configuration

This API is used to update an existing Tenant Manager identity provider type configuration.

You must specify all of the properties of the identity provider type configuration when calling this API with the `PUT` HTTP method. When used with `PUT`, this API doesn't merge the existing type configuration and your new data. It replaces the existing type configuration with your new data.

Utilize the `PATCH` HTTP method to send specific changes to merge into an existing type configuration.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Update a Tenant Manager identity provider type configuration

PUT/api/tenant-manager/identity-provider/{type}

OpenAPI Spec

PATCH/api/tenant-manager/identity-provider/{type}

OpenAPI Spec

note

For backward compatibility, the `PATCH` method accepts the same media type (specified by a `Content-Type` of `application/json`) and body as the `PUT` request. You can also use the following media types for different behavior:

*   [JSON Patch/RFC 6902](https://www.rfc-editor.org/rfc/rfc6902): `application/json-patch+json`
*   [JSON Merge Patch/RFC 7396](https://www.rfc-editor.org/rfc/rfc7396): `merge-patch+json`

For details, see the [PATCH documentation](https://fusionauth.io/docs/apis.md#the-patch-http-method).

Using a media type of `application/json` merges the provided request parameters into the existing object. As a result, all parameters are optional with `PATCH`: only provide the values you want to change. To remove a value, provide a `null` value. Patching an `Array` appends all values in the new list to the old list.

#### Request Parameters

`type`Stringrequired

The identity provider type key. Valid values are `OpenIDConnect` and `SAMLv2`.

#### Request Body

`typeConfiguration.defaultAttributeMappings`Map<String, String>optional

A map of default attribute mappings. Mapping keys not present in the configured Tenant Manager attribute form are removed before persistence.

`typeConfiguration.defaultAttributeMappings[key]`Stringoptional

The source expression used to populate the mapped FusionAuth user or registration field.

`typeConfiguration.enabled`BooleanoptionalDefaults to true

Whether this identity provider type is enabled for Tenant Manager.

`typeConfiguration.linkingStrategy`Stringoptional

The linking strategy for this identity provider type. Required when creating or replacing a type configuration. Valid values are `LinkByEmail`, `LinkByEmailForExistingUser`, `LinkByUsername`, and `LinkByUsernameForExistingUser`.

`typeConfiguration.type`Stringoptional

The identity provider type key. This value is read from the URI path parameter and any value provided in the request body is ignored.

*Example Request JSON*

```json
{
  "typeConfiguration": {
    "defaultAttributeMappings": {
      "registration.data.department": "department",
      "registration.username": "preferred_username",
      "user.email": "email",
      "user.firstName": "given_name"
    },
    "enabled": true,
    "linkingStrategy": "LinkByEmail"
  }
}
```

note

The `type` value is read from the URI path parameter. Any `typeConfiguration.type` value supplied in the request body is ignored.

### Response

The response for this API contains the updated identity provider type configuration.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The object you are trying to update doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |

#### Response Body

`typeConfiguration.defaultAttributeMappings`Map<String, String>

A map of default attribute mappings for this identity provider type.

`typeConfiguration.defaultAttributeMappings[key]`String

The source expression used to populate the mapped FusionAuth user or registration field.

`typeConfiguration.enabled`Boolean

Whether this identity provider type is enabled for Tenant Manager.

`typeConfiguration.insertInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this identity provider type configuration was created.

`typeConfiguration.lastUpdateInstant`Long

The [instant](https://fusionauth.io/docs/reference/data-types.md#instants) that this identity provider type configuration was last updated.

`typeConfiguration.linkingStrategy`String

The linking strategy for this identity provider type configuration.

`typeConfiguration.type`String

The identity provider type key for this configuration.

*Example JSON Response*

```json
{
  "typeConfiguration": {
    "defaultAttributeMappings": {
      "registration.data.department": "department",
      "registration.username": "preferred_username",
      "user.email": "email",
      "user.firstName": "given_name"
    },
    "enabled": true,
    "insertInstant": 1776791200111,
    "lastUpdateInstant": 1776791266333,
    "linkingStrategy": "LinkByEmail",
    "type": "OpenIDConnect"
  }
}
```

### Delete a Tenant Manager Identity Provider Type Configuration

This API is used to delete an existing Tenant Manager identity provider type configuration.

### Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Delete a Tenant Manager identity provider type configuration

DELETE/api/tenant-manager/identity-provider/{type}

OpenAPI Spec

#### Request Parameters

`type`Stringrequired

The identity provider type key. Valid values are `OpenIDConnect` and `SAMLv2`.

### Response

This API does not return a JSON response body.

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 404 | The object you requested doesn't exist. The response will be empty. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |