Tenant Manager API
On this page
This page contains the APIs used to retrieve and update Tenant Manager configuration.
Available since1.65.0
Retrieve Tenant Manager Configuration#
This API is used to retrieve the Tenant Manager configuration singleton.
Request#
Retrieve the Tenant Manager configuration.
OpenAPI Spec
Response#
The response for this API contains the Tenant Manager configuration.
| Code | Description |
|---|---|
| 200 | The request succeeded. The response contains a JSON body. |
| 401 | The request has no valid Authorization header. The header is missing, or the API key isn't valid. The response is empty. For more information, see Authentication. |
| 500 | FusionAuth had an internal error and logged a stack trace in the FusionAuth log files. The response is empty. |
| 503 | The search index is unavailable or returned an error, so FusionAuth can't complete the request. The response contains a JSON body. |
Response Body#
tenantManagerConfiguration.applicationConfigurations The list of universal applications that are enabled for Tenant Manager identity providers.
tenantManagerConfiguration.applicationConfigurations[x].applicationId The Id of a universal application enabled for Tenant Manager identity providers.
tenantManagerConfiguration.attributeFormId The Id of the registration form used to determine available attribute mapping targets.
tenantManagerConfiguration.brandName The brand name displayed in Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurations A map of tenant manager IdP type configurations keyed by Identity Provider type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].defaultAttributeMappings Default attribute mappings for this allowed Identity Provider type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].enabled Whether this Identity Provider type is enabled for Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstant The instant that this Identity Provider type configuration was created.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstant The instant that this Identity Provider type configuration was last updated.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategy The linking strategy used for Identity Providers of this type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].type The identity provider type key for this configuration.
tenantManagerConfiguration.insertInstant The instant that the Tenant Manager configuration was created.
tenantManagerConfiguration.lastUpdateInstant The instant that the Tenant Manager configuration was last updated.
{
"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#
Send the full Tenant Manager configuration with your changes applied.
OpenAPI Spec
OpenAPI Spec
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.applicationConfigurations The list of universal applications enabled for Tenant Manager identity providers.
tenantManagerConfiguration.applicationConfigurations[x].applicationId The Id of a universal application enabled for Tenant Manager identity providers.
tenantManagerConfiguration.attributeFormId The Id of the registration form used to determine available attribute mapping targets.
tenantManagerConfiguration.brandName The brand name displayed in Tenant Manager.
{
"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.
| Code | Description |
|---|---|
| 200 | The request succeeded. The response contains a JSON body. |
| 400 | The request was invalid or malformed. The response contains an Errors JSON object with the specific errors. FusionAuth also returns a 400 when the request needs a paid FusionAuth license and no license is present. |
| 401 | The request has no valid Authorization header. The header is missing, or the API key isn't valid. The response is empty. For more information, see Authentication. |
| 500 | FusionAuth had an internal error and logged a stack trace in the FusionAuth log files. The response is empty. |
| 503 | The search index is unavailable or returned an error, so FusionAuth can't complete the request. The response contains a JSON body. |
Response Body#
tenantManagerConfiguration.applicationConfigurations The list of universal applications that are enabled for Tenant Manager identity providers.
tenantManagerConfiguration.applicationConfigurations[x].applicationId The Id of a universal application enabled for Tenant Manager identity providers.
tenantManagerConfiguration.attributeFormId The Id of the registration form used to determine available attribute mapping targets.
tenantManagerConfiguration.brandName The brand name displayed in Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurations A map of tenant manager IdP type configurations keyed by Identity Provider type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].defaultAttributeMappings Default attribute mappings for this allowed Identity Provider type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].enabled Whether this Identity Provider type is enabled for Tenant Manager.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].insertInstant The instant that this Identity Provider type configuration was created.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].lastUpdateInstant The instant that this Identity Provider type configuration was last updated.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].linkingStrategy The linking strategy used for Identity Providers of this type.
tenantManagerConfiguration.identityProviderTypeConfigurations[type].type The identity provider type key for this configuration.
tenantManagerConfiguration.insertInstant The instant that the Tenant Manager configuration was created.
tenantManagerConfiguration.lastUpdateInstant The instant that the Tenant Manager configuration was last updated.
{
"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#
Create a Tenant Manager identity provider type configuration for the given type.
OpenAPI Spec
Path Parameters#
typeThe identity provider type key. Valid values are OpenIDConnect and SAMLv2.
Request Body#
typeConfiguration.defaultAttributeMappings A map of default attribute mappings. Mapping keys not present in the configured Tenant Manager attribute form are removed before persistence.
typeConfiguration.defaultAttributeMappings[key] The source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabled Whether this identity provider type is enabled for Tenant Manager.
typeConfiguration.linkingStrategy 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 The identity provider type key. This value is read from the URI path parameter and any value provided in the request body is ignored.
{
"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.
| Code | Description |
|---|---|
| 200 | The request succeeded. The response contains a JSON body. |
| 400 | The request was invalid or malformed. The response contains an Errors JSON object with the specific errors. FusionAuth also returns a 400 when the request needs a paid FusionAuth license and no license is present. |
| 401 | The request has no valid Authorization header. The header is missing, or the API key isn't valid. The response is empty. For more information, see Authentication. |
| 500 | FusionAuth had an internal error and logged a stack trace in the FusionAuth log files. The response is empty. |
Response Body#
typeConfiguration.defaultAttributeMappings A map of default attribute mappings for this identity provider type.
typeConfiguration.defaultAttributeMappings[key] The source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabled Whether this identity provider type is enabled for Tenant Manager.
typeConfiguration.insertInstant The instant that this identity provider type configuration was created.
typeConfiguration.lastUpdateInstant The instant that this identity provider type configuration was last updated.
typeConfiguration.linkingStrategy The linking strategy for this identity provider type configuration.
typeConfiguration.type The identity provider type key for this configuration.
{
"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#
Update the Tenant Manager identity provider type configuration by its type.
OpenAPI Spec
OpenAPI Spec
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.
Path Parameters#
typeThe identity provider type key. Valid values are OpenIDConnect and SAMLv2.
Request Body#
typeConfiguration.defaultAttributeMappings A map of default attribute mappings. Mapping keys not present in the configured Tenant Manager attribute form are removed before persistence.
typeConfiguration.defaultAttributeMappings[key] The source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabled Whether this identity provider type is enabled for Tenant Manager.
typeConfiguration.linkingStrategy 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 The identity provider type key. This value is read from the URI path parameter and any value provided in the request body is ignored.
{
"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.
| Code | Description |
|---|---|
| 200 | The request succeeded. The response contains a JSON body. |
| 400 | The request was invalid or malformed. The response contains an Errors JSON object with the specific errors. FusionAuth also returns a 400 when the request needs a paid FusionAuth license and no license is present. |
| 401 | The request has no valid Authorization header. The header is missing, or the API key isn't valid. The response is empty. For more information, see Authentication. |
| 404 | The object you're updating doesn't exist. The response is empty. |
| 500 | FusionAuth had an internal error and logged a stack trace in the FusionAuth log files. The response is empty. |
Response Body#
typeConfiguration.defaultAttributeMappings A map of default attribute mappings for this identity provider type.
typeConfiguration.defaultAttributeMappings[key] The source expression used to populate the mapped FusionAuth user or registration field.
typeConfiguration.enabled Whether this identity provider type is enabled for Tenant Manager.
typeConfiguration.insertInstant The instant that this identity provider type configuration was created.
typeConfiguration.lastUpdateInstant The instant that this identity provider type configuration was last updated.
typeConfiguration.linkingStrategy The linking strategy for this identity provider type configuration.
typeConfiguration.type The identity provider type key for this configuration.
{
"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#
Delete the Tenant Manager identity provider type configuration by its type.
OpenAPI Spec
Path Parameters#
typeThe identity provider type key. Valid values are OpenIDConnect and SAMLv2.
Response#
This API does not return a JSON response body.
| Code | Description |
|---|---|
| 200 | The request succeeded. |
| 400 | The request was invalid or malformed. The response contains an Errors JSON object with the specific errors. FusionAuth also returns a 400 when the request needs a paid FusionAuth license and no license is present. |
| 401 | The request has no valid Authorization header. The header is missing, or the API key isn't valid. The response is empty. For more information, see Authentication. |
| 404 | The object you requested doesn't exist. The response is empty. |
| 500 | FusionAuth had an internal error and logged a stack trace in the FusionAuth log files. The response is empty. |
Related
API documentation for the FusionAuth Create a Tenant API.
API documentation for the FusionAuth Delete a Tenant API.
Learn about the APIs for creating, retrieving, updating and deleting tenants.
API documentation for the FusionAuth Retrieve a Tenant API.