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#
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].applicationIdUUIDThe Id of a universal application enabled for Tenant Manager identity providers.
tenantManagerConfiguration.attributeFormIdUUIDThe Id of the registration form used to determine available attribute mapping targets.
tenantManagerConfiguration.brandNameStringThe brand name displayed in Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurationsObjectA 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].enabledBooleanWhether this Identity Provider type is enabled for Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstantLongThe instant that this Identity Provider type configuration was created.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstantLongThe instant that this Identity Provider type configuration was last updated.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategyStringThe linking strategy used for Identity Providers of this type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].typeStringThe identity provider type key for this configuration.
tenantManagerConfiguration.insertInstantLongThe instant that the Tenant Manager configuration was created.
tenantManagerConfiguration.lastUpdateInstantLongThe 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#
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:
application/json-patch+json - JSON Merge Patch/RFC 7396:
merge-patch+json
For details, see the PATCH documentation.
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.applicationConfigurationsArray<Object>The list of universal applications enabled for Tenant Manager identity providers.
tenantManagerConfiguration.applicationConfigurations[x].applicationIdUUIDThe Id of a universal application enabled for Tenant Manager identity providers.
tenantManagerConfiguration.attributeFormIdUUIDThe Id of the registration form used to determine available attribute mapping targets.
tenantManagerConfiguration.brandNameStringThe 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].applicationIdUUIDThe Id of a universal application enabled for Tenant Manager identity providers.
tenantManagerConfiguration.attributeFormIdUUIDThe Id of the registration form used to determine available attribute mapping targets.
tenantManagerConfiguration.brandNameStringThe brand name displayed in Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurationsObjectA 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].enabledBooleanWhether this Identity Provider type is enabled for Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstantLongThe instant that this Identity Provider type configuration was created.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstantLongThe instant that this Identity Provider type configuration was last updated.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategyStringThe linking strategy used for Identity Providers of this type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].typeStringThe identity provider type key for this configuration.
tenantManagerConfiguration.insertInstantLongThe instant that the Tenant Manager configuration was created.
tenantManagerConfiguration.lastUpdateInstantLongThe 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#
Request Parameters#
typeStringrequiredThe 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]StringThe source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabledBooleanDefaults to trueWhether this identity provider type is enabled for Tenant Manager.
typeConfiguration.linkingStrategyStringThe linking strategy for this identity provider type. Required when creating or replacing a type configuration. Valid values are LinkByEmail, LinkByEmailForExistingUser, LinkByUsername, and LinkByUsernameForExistingUser.
typeConfiguration.typeStringThe 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]StringThe source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabledBooleanWhether this identity provider type is enabled for Tenant Manager.
typeConfiguration.insertInstantLongThe instant that this identity provider type configuration was created.
typeConfiguration.lastUpdateInstantLongThe instant that this identity provider type configuration was last updated.
typeConfiguration.linkingStrategyStringThe linking strategy for this identity provider type configuration.
typeConfiguration.typeStringThe 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#
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:
application/json-patch+json - JSON Merge Patch/RFC 7396:
merge-patch+json
For details, see the PATCH documentation.
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#
typeStringrequiredThe 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]StringThe source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabledBooleanDefaults to trueWhether this identity provider type is enabled for Tenant Manager.
typeConfiguration.linkingStrategyStringThe linking strategy for this identity provider type. Required when creating or replacing a type configuration. Valid values are LinkByEmail, LinkByEmailForExistingUser, LinkByUsername, and LinkByUsernameForExistingUser.
typeConfiguration.typeStringThe 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]StringThe source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabledBooleanWhether this identity provider type is enabled for Tenant Manager.
typeConfiguration.insertInstantLongThe instant that this identity provider type configuration was created.
typeConfiguration.lastUpdateInstantLongThe instant that this identity provider type configuration was last updated.
typeConfiguration.linkingStrategyStringThe linking strategy for this identity provider type configuration.
typeConfiguration.typeStringThe 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#
Request Parameters#
typeStringrequiredThe 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. |