/ Docs

Tenant Manager API

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

This API has been available since 1.65.0

Retrieve Tenant Manager Configuration#

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

Request#

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.
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.applicationConfigurationsArray<Object>

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

tenantManagerConfiguration.applicationConfigurations[x].applicationIdUUID

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

tenantManagerConfiguration.attributeFormIdUUID

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

tenantManagerConfiguration.brandNameString

The brand name displayed in Tenant Manager.

tenantManagerConfiguration.identityProviderTypeConfigurationsObject

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

tenantManagerConfiguration.identityProviderTypeConfigurations[type].defaultAttributeMappingsMap<String, String>

Default attribute mappings for this allowed Identity Provider type.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].enabledBoolean

Whether this Identity Provider type is enabled for Tenant Manager.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstantLong

The instant that this Identity Provider type configuration was created.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstantLong

The instant that this Identity Provider type configuration was last updated.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategyString

The linking strategy used for Identity Providers of this type.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].typeString

The identity provider type key for this configuration.

tenantManagerConfiguration.insertInstantLong

The instant that the Tenant Manager configuration was created.

tenantManagerConfiguration.lastUpdateInstantLong

The instant that the Tenant Manager configuration was last updated.

Example JSON Response

{
  "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
Update the Tenant Manager configuration
PUT /api/tenant-manager
PATCH /api/tenant-manager

When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902] or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.

When using the PATCH method with a Content-Type of application/json the provided request parameters will be merged into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

Request Body#

tenantManagerConfiguration.applicationConfigurationsArray<Object>

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

tenantManagerConfiguration.applicationConfigurations[x].applicationIdUUID

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

tenantManagerConfiguration.attributeFormIdUUID

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

tenantManagerConfiguration.brandNameString

The brand name displayed in Tenant Manager.

Example Request 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 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.
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.applicationConfigurationsArray<Object>

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

tenantManagerConfiguration.applicationConfigurations[x].applicationIdUUID

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

tenantManagerConfiguration.attributeFormIdUUID

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

tenantManagerConfiguration.brandNameString

The brand name displayed in Tenant Manager.

tenantManagerConfiguration.identityProviderTypeConfigurationsObject

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

tenantManagerConfiguration.identityProviderTypeConfigurations[type].defaultAttributeMappingsMap<String, String>

Default attribute mappings for this allowed Identity Provider type.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].enabledBoolean

Whether this Identity Provider type is enabled for Tenant Manager.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstantLong

The instant that this Identity Provider type configuration was created.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstantLong

The instant that this Identity Provider type configuration was last updated.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategyString

The linking strategy used for Identity Providers of this type.

tenantManagerConfiguration.identityProviderTypeConfigurations[type].typeString

The identity provider type key for this configuration.

tenantManagerConfiguration.insertInstantLong

The instant that the Tenant Manager configuration was created.

tenantManagerConfiguration.lastUpdateInstantLong

The instant that the Tenant Manager configuration was last updated.

Example JSON Response

{
  "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.

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
Create a Tenant Manager identity provider type configuration
POST /api/tenant-manager/identity-provider/{type}

Request Parameters#

typeStringrequired

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

Request Body#

typeConfiguration.defaultAttributeMappingsMap<String, String>

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

typeConfiguration.defaultAttributeMappings[key]String

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

typeConfiguration.enabledBooleanDefaults to true

Whether this identity provider type is enabled for Tenant Manager.

typeConfiguration.linkingStrategyString

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

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

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

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

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 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.
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.defaultAttributeMappingsMap<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.enabledBoolean

Whether this identity provider type is enabled for Tenant Manager.

typeConfiguration.insertInstantLong

The instant that this identity provider type configuration was created.

typeConfiguration.lastUpdateInstantLong

The instant that this identity provider type configuration was last updated.

typeConfiguration.linkingStrategyString

The linking strategy for this identity provider type configuration.

typeConfiguration.typeString

The identity provider type key for this configuration.

Example JSON Response

{
  "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
Update a Tenant Manager identity provider type configuration
PUT /api/tenant-manager/identity-provider/{type}
PATCH /api/tenant-manager/identity-provider/{type}

When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902] or JSON Merge Patch/RFC 7396. See the PATCH documentation for more information.

When using the PATCH method with a Content-Type of application/json the provided request parameters will be merged into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A null value can be used to remove a value. Patching an Array will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.

Request Parameters#

typeStringrequired

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

Request Body#

typeConfiguration.defaultAttributeMappingsMap<String, String>

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

typeConfiguration.defaultAttributeMappings[key]String

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

typeConfiguration.enabledBooleanDefaults to true

Whether this identity provider type is enabled for Tenant Manager.

typeConfiguration.linkingStrategyString

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

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

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

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 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.
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.defaultAttributeMappingsMap<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.enabledBoolean

Whether this identity provider type is enabled for Tenant Manager.

typeConfiguration.insertInstantLong

The instant that this identity provider type configuration was created.

typeConfiguration.lastUpdateInstantLong

The instant that this identity provider type configuration was last updated.

typeConfiguration.linkingStrategyString

The linking strategy for this identity provider type configuration.

typeConfiguration.typeString

The identity provider type key for this configuration.

Example JSON Response

{
  "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
Delete a Tenant Manager identity provider type configuration
DELETE /api/tenant-manager/identity-provider/{type}

Request Parameters#

typeStringrequired

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