Tenant APIs - Home - FusionAuth

1. Overview

A FusionAuth Tenant is a named object that represents a discrete namespace for Users, Applications and Groups. A user is unique by email address or username within a tenant.

Tenants may be useful to support a multi-tenant application where you wish to use a single instance of FusionAuth but require the ability to have duplicate users across the tenants in your own application. In this scenario a user may exist multiple times with the same email address and different passwords across tenants.

Tenants may also be useful in a test or staging environment to allow multiple users to call APIs and create and modify users without possibility of collision.

The following APIs are provided to manage Tenants.

Create a Tenant
Retrieve a Tenant
Update a Tenant
Delete a Tenant

2. Create a Tenant

This API is used to create a new Tenant.

2.1. Request

Create a Tenant with a randomly generated Id

URI

POST /api/tenant

Create a Tenant with the provided unique Id

URI

POST /api/tenant/{tenantId}

Table 1. Request Parameters
tenantId [UUID] Optional defaults to secure random UUID	The Id to use for the new Tenant. If not specified a secure random UUID will be generated.

Table 2. Request Body
tenant.data [Object] Optional	An object that can hold any information about the Tenant that should be persisted.
tenant.emailConfiguration.enabled [Boolean] Optional Deprecated	When this value is set to true the email configuration provided by this tenant will take precedence over the configuration by the System Configuration. Removed in version 1.8.0 In version 1.8.0 and beyond, a Tenant’s email configuration is enabled upon configuration.
tenant.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user is sent a forgot password email.
tenant.emailConfiguration.host [String] Required Available Since 1.8.0	The host name of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.password [String] Optional Available Since 1.8.0	An optional password FusionAuth will use to authenticate with the SMTP server.
tenant.emailConfiguration.port [Integer] Required Available Since 1.8.0	The port of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.
tenant.emailConfiguration.security String Optional defaults to NONE Available Since 1.8.0	The type of security protocol FusionAuth will use when connecting to the SMTP server. The possible values are: `NONE` - no security will be used. All communications will be sent plaintext. `SSL` - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports. `TLS` - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.
tenant.emailConfiguration.username [String] Optional Available Since 1.8.0	An optional username FusionAuth will to authenticate with the SMTP server.
tenant.emailConfiguration.verificationEmailTemplateId [UUID] Optional	The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the `verifyEmail` field is `true` this field is required.
tenant.emailConfiguration.verifyEmail [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the registers with your application.
tenant.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the user changes them.
tenant.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint. Value must be greater than 0 and less than or equal to 600.
tenant.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.oneTimePasswordTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a One Time Password is no longer valid and cannot be used by the Login API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.passwordlessLoginTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a passwordless code is no longer valid and cannot be used by the Passwordless API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt. Value must be greater than 0.
tenant.failedAuthenticationConfiguration.actionDuration [Long] Optional defaults to `3` Available Since 1.8.0	The duration of the User Action. This value along with the `actionDurationUnit` will be used to set the duration of the User Action.
tenant.failedAuthenticationConfiguration.actionDurationUnit [String] Optional defaults to `"MINUTES"` Available Since 1.8.0	The unit of time associated with a duration. The possible values are: `MINUTES` `HOURS` `DAYS` `WEEKS` `MONTHS` `YEARS`
tenant.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Optional defaults to `60` Available Since 1.8.0	The length of time in seconds before the failed authentication count will be reset. For example, if `tooManyAttempts` is set to `5` and you fail to authenticate `4` times in a row, waiting for the duration specified here will cause your fifth attempt to start back at `1`.
tenant.failedAuthenticationConfiguration.tooManyAttempts [Integer] Optional defaults to `5` Available Since 1.8.0	The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.
tenant.failedAuthenticationConfiguration.userActionId [UUID] Optional Available Since 1.8.0	The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
tenant.maximumPasswordAge.days [Integer] Optional defaults to `180` Available Since 1.8.0	The password maximum age in days. The number of days after which FusionAuth will require a user to change their password. Required when `systemConfiguration.maximumPasswordAge.enabled` is set to `true`.
tenant.maximumPasswordAge.enabled [Boolean] Optional defaults to `false` Available Since 1.8.0	Indicates that the maximum password age is enabled and being enforced.
tenant.minimumPasswordAge.seconds [Integer] Optional defaults to `30` Available Since 1.8.0	The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age. Required when `systemConfiguration.minimumPasswordAge.enabled` is set to `true`.
tenant.minimumPasswordAge.enabled [Boolean] Optional defaults to `false` Available Since 1.8.0	Indicates that the minimum password age is enabled and being enforced.
tenant.name [String] Required	The name of the Tenant.
tenant.passwordEncryptionConfiguration.encryptionScheme [String] Optional defaults to `"salted-pbkdf2-hmac-sha256"` Available Since 1.8.0	The default method for encrypting the User’s password. The following encryptors are provided with FusionAuth: `salted-md5` `salted-sha256` `salted-hmac-sha256` `salted-pbkdf2-hmac-sha256` `bcrypt`
tenant.passwordEncryptionConfiguration.encryptionSchemeFactor [Integer] Optional defaults to `24000` Available Since 1.8.0	The factor used by the password encryption scheme. If not provided, the `PasswordEncryptor` provides a default value. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the `PasswordEncryptor` implementation.
tenant.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Optional defaults to `false` Available Since 1.8.0	When enabled a user’s hash configuration will be modified to match these configured settings. This can be useful to increase a password hash strength over time or upgrade imported users to a more secure encryption scheme after an initial import.

Example Request JSON

{
  "tenant": {
    "data": {
      "description": "No more secrets, Marty."
    },
    "emailConfiguration": {
      "forgotPasswordEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
      "host": "smtp.sendgrid.net",
      "password": "password",
      "passwordlessEmailTemplateId": "a917e23a-da58-4cda-be01-90f542f8c343",
      "port": 587,
      "security": "TLS",
      "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
      "username": "username",
      "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87ab5",
      "verifyEmail": true,
      "verifyEmailWhenChanged": true
    },
    "externalIdentifierConfiguration": {
      "authorizationGrantIdTimeToLiveInSeconds": 30,
      "changePasswordIdTimeToLiveInSeconds": 600,
      "emailVerificationIdTimeToLiveInSeconds": 86400,
      "oneTimePasswordTimeToLiveInSeconds": 60,
      "passwordlessLoginTimeToLiveInSeconds": 180,
      "registrationVerificationIdTimeToLiveInSeconds": 86400,
      "setupPasswordIdTimeToLiveInSeconds": 86400,
      "twoFactorIdTimeToLiveInSeconds": 300,
      "twoFactorTrustIdTimeToLiveInSeconds": 2592000
    },
    "failedAuthenticationConfiguration": {
      "actionDuration": 3,
      "actionDurationUnit": "MINUTES",
      "resetCountInSeconds": 60,
      "tooManyAttempts": 5,
      "userActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4"
    },
    "maximumPasswordAge": {
      "days": 180,
      "enabled": false
    },
    "minimumPasswordAge": {
      "enabled": false,
      "seconds": 30
    },
    "name": "Playtronics Co.",
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    }
  }
}

2.2. Response

The response for this API contains the Tenant that was created.

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

Table 4. Response Body for a single Tenant
tenant.data [Object]	An object that can hold any information about the Tenant that should be persisted.
tenant.emailConfiguration.enabled [Boolean] Optional Deprecated	When this value is set to true the email configuration provided by this tenant will take precedence over the configuration by the System Configuration. Removed in version 1.8.0 In version 1.8.0 and beyond, a Tenant’s email configuration is enabled upon configuration.
tenant.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user is sent a forgot password email.
tenant.emailConfiguration.host [String] Required Available Since 1.8.0	The host name of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.password [String] Optional Available Since 1.8.0	An optional password FusionAuth will use to authenticate with the SMTP server.
tenant.emailConfiguration.port [Integer] Required Available Since 1.8.0	The port of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional Available Since 1.8.0	The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.
tenant.emailConfiguration.security String Optional defaults to NONE Available Since 1.8.0	The type of security protocol FusionAuth will use when connecting to the SMTP server. The possible values are: `NONE` - no security will be used. All communications will be sent plaintext. `SSL` - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports. `TLS` - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.
tenant.emailConfiguration.username [String] Optional Available Since 1.8.0	An optional username FusionAuth will to authenticate with the SMTP server.
tenant.emailConfiguration.verificationEmailTemplateId [UUID] Optional	The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the `verifyEmail` field is `true` this field is required.
tenant.emailConfiguration.verifyEmail [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the registers with your application.
tenant.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the user changes them.
tenant.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint.
tenant.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.
tenant.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.
tenant.externalIdentifierConfiguration.passwordlessLoginTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a passwordless code is no longer valid and cannot be used by the Passwordless API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.
tenant.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.
tenant.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.
tenant.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt.
tenant.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.8.0	The duration of the User Action. This value along with the `actionDurationUnit` will be used to set the duration of the User Action.
tenant.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.8.0	The unit of time associated with a duration. The possible values are: `MINUTES` `HOURS` `DAYS` `WEEKS` `MONTHS` `YEARS`
tenant.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.8.0	The length of time in seconds before the failed authentication count will be reset. For example, if `tooManyAttempts` is set to `5` and you fail to authenticate `4` times in a row, waiting for the duration specified here will cause your fifth attempt to start back at `1`.
tenant.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.8.0	The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.
tenant.failedAuthenticationConfiguration.userActionId [UUID] Available Since 1.8.0	The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
tenant.maximumPasswordAge.days [Integer] Available Since 1.8.0	The password maximum age in days. The number of days after which FusionAuth will require a user to change their password.
tenant.maximumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the maximum password age is enabled and being enforced.
tenant.minimumPasswordAge.seconds [Integer] Available Since 1.8.0	The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age.
tenant.minimumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the minimum password age is enabled and being enforced.
tenant.id [UUID]	The unique Id of the Tenant.
tenant.name [String]	The name of the Tenant.
tenant.passwordEncryptionConfiguration.encryptionScheme [String] Available Since 1.8.0	The selected default encryption scheme.
tenant.passwordEncryptionConfiguration.encryptionSchemeFactor [Integer] Available Since 1.8.0	The factor used by the password encryption scheme. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the `PasswordEncryptor` implementation.
tenant.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Available Since 1.8.0	When enabled a user’s hash configuration will be modified to match these configured settings.

Example Response JSON

{
  "tenant": {
    "data": {
      "description": "No more secrets, Marty."
    },
    "emailConfiguration": {
      "forgotPasswordEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
      "host": "smtp.sendgrid.net",
      "password": "password",
      "passwordlessEmailTemplateId": "a917e23a-da58-4cda-be01-90f542f8c343",
      "port": 587,
      "security": "TLS",
      "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
      "username": "username",
      "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87ab5",
      "verifyEmail": true,
      "verifyEmailWhenChanged": true
    },
    "externalIdentifierConfiguration": {
      "authorizationGrantIdTimeToLiveInSeconds": 30,
      "changePasswordIdTimeToLiveInSeconds": 600,
      "emailVerificationIdTimeToLiveInSeconds": 86400,
      "oneTimePasswordTimeToLiveInSeconds": 60,
      "passwordlessLoginTimeToLiveInSeconds": 180,
      "registrationVerificationIdTimeToLiveInSeconds": 86400,
      "setupPasswordIdTimeToLiveInSeconds": 86400,
      "twoFactorIdTimeToLiveInSeconds": 300,
      "twoFactorTrustIdTimeToLiveInSeconds": 2592000
    },
    "failedAuthenticationConfiguration": {
      "actionDuration": 3,
      "actionDurationUnit": "MINUTES",
      "resetCountInSeconds": 60,
      "tooManyAttempts": 5,
      "userActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4"
    },
    "id": "2321c2ab-0848-45fc-995b-869ba82c2a8c",
    "maximumPasswordAge": {
      "days": 180,
      "enabled": false
    },
    "minimumPasswordAge": {
      "enabled": false,
      "seconds": 30
    },
    "name": "Playtronics Co.",
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    }
  }
}

3. Retrieve a Tenant

This API is used to retrieve a single Tenant by unique Id or all of the configured Tenants.

3.1. Request

Retrieve all of the Tenants

URI

GET /api/tenant

Retrieve a Tenant by Id

URI

GET /api/tenant/{tenantId}

Table 5. Request Parameters
tenantId [UUID] Required	The unique Id of the Tenant to retrieve.

3.2. Response

The response for this API contains either a single Tenant or all of the Tenants. When you call this API with an Id the response will contain a single Tenant. When you call this API without an Id the response will contain all of the Tenants. Both response types are defined below along with an example JSON response.

Table 6. 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.
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.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 7. Response Body for a single Tenant
tenant.data [Object]	An object that can hold any information about the Tenant that should be persisted.
tenant.emailConfiguration.enabled [Boolean] Optional Deprecated	When this value is set to true the email configuration provided by this tenant will take precedence over the configuration by the System Configuration. Removed in version 1.8.0 In version 1.8.0 and beyond, a Tenant’s email configuration is enabled upon configuration.
tenant.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user is sent a forgot password email.
tenant.emailConfiguration.host [String] Required Available Since 1.8.0	The host name of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.password [String] Optional Available Since 1.8.0	An optional password FusionAuth will use to authenticate with the SMTP server.
tenant.emailConfiguration.port [Integer] Required Available Since 1.8.0	The port of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional Available Since 1.8.0	The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.
tenant.emailConfiguration.security String Optional defaults to NONE Available Since 1.8.0	The type of security protocol FusionAuth will use when connecting to the SMTP server. The possible values are: `NONE` - no security will be used. All communications will be sent plaintext. `SSL` - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports. `TLS` - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.
tenant.emailConfiguration.username [String] Optional Available Since 1.8.0	An optional username FusionAuth will to authenticate with the SMTP server.
tenant.emailConfiguration.verificationEmailTemplateId [UUID] Optional	The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the `verifyEmail` field is `true` this field is required.
tenant.emailConfiguration.verifyEmail [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the registers with your application.
tenant.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the user changes them.
tenant.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint.
tenant.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.
tenant.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.
tenant.externalIdentifierConfiguration.passwordlessLoginTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a passwordless code is no longer valid and cannot be used by the Passwordless API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.
tenant.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.
tenant.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.
tenant.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt.
tenant.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.8.0	The duration of the User Action. This value along with the `actionDurationUnit` will be used to set the duration of the User Action.
tenant.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.8.0	The unit of time associated with a duration. The possible values are: `MINUTES` `HOURS` `DAYS` `WEEKS` `MONTHS` `YEARS`
tenant.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.8.0	The length of time in seconds before the failed authentication count will be reset. For example, if `tooManyAttempts` is set to `5` and you fail to authenticate `4` times in a row, waiting for the duration specified here will cause your fifth attempt to start back at `1`.
tenant.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.8.0	The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.
tenant.failedAuthenticationConfiguration.userActionId [UUID] Available Since 1.8.0	The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
tenant.maximumPasswordAge.days [Integer] Available Since 1.8.0	The password maximum age in days. The number of days after which FusionAuth will require a user to change their password.
tenant.maximumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the maximum password age is enabled and being enforced.
tenant.minimumPasswordAge.seconds [Integer] Available Since 1.8.0	The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age.
tenant.minimumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the minimum password age is enabled and being enforced.
tenant.id [UUID]	The unique Id of the Tenant.
tenant.name [String]	The name of the Tenant.
tenant.passwordEncryptionConfiguration.encryptionScheme [String] Available Since 1.8.0	The selected default encryption scheme.
tenant.passwordEncryptionConfiguration.encryptionSchemeFactor [Integer] Available Since 1.8.0	The factor used by the password encryption scheme. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the `PasswordEncryptor` implementation.
tenant.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Available Since 1.8.0	When enabled a user’s hash configuration will be modified to match these configured settings.

Example Response JSON

{
  "tenant": {
    "data": {
      "description": "No more secrets, Marty."
    },
    "emailConfiguration": {
      "forgotPasswordEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
      "host": "smtp.sendgrid.net",
      "password": "password",
      "passwordlessEmailTemplateId": "a917e23a-da58-4cda-be01-90f542f8c343",
      "port": 587,
      "security": "TLS",
      "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
      "username": "username",
      "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87ab5",
      "verifyEmail": true,
      "verifyEmailWhenChanged": true
    },
    "externalIdentifierConfiguration": {
      "authorizationGrantIdTimeToLiveInSeconds": 30,
      "changePasswordIdTimeToLiveInSeconds": 600,
      "emailVerificationIdTimeToLiveInSeconds": 86400,
      "oneTimePasswordTimeToLiveInSeconds": 60,
      "passwordlessLoginTimeToLiveInSeconds": 180,
      "registrationVerificationIdTimeToLiveInSeconds": 86400,
      "setupPasswordIdTimeToLiveInSeconds": 86400,
      "twoFactorIdTimeToLiveInSeconds": 300,
      "twoFactorTrustIdTimeToLiveInSeconds": 2592000
    },
    "failedAuthenticationConfiguration": {
      "actionDuration": 3,
      "actionDurationUnit": "MINUTES",
      "resetCountInSeconds": 60,
      "tooManyAttempts": 5,
      "userActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4"
    },
    "id": "2321c2ab-0848-45fc-995b-869ba82c2a8c",
    "maximumPasswordAge": {
      "days": 180,
      "enabled": false
    },
    "minimumPasswordAge": {
      "enabled": false,
      "seconds": 30
    },
    "name": "Playtronics Co.",
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    }
  }
}

Table 8. Response Body for all Tenants
tenants [Array]	The list of Tenant objects.
tenants`[x]`.data [Object]	An object that can hold any information about the Tenant that should be persisted.
tenants`[x]`.emailConfiguration.enabled [Boolean] Optional Deprecated	When this value is set to true the email configuration provided by this tenant will take precedence over the configuration by the System Configuration. Removed in version 1.8.0 In version 1.8.0 and beyond, a Tenant’s email configuration is enabled upon configuration.
tenants`[x]`.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user is sent a forgot password email.
tenants`[x]`.emailConfiguration.host [String] Required Available Since 1.8.0	The host name of the SMTP server that FusionAuth will use.
tenants`[x]`.emailConfiguration.password [String] Optional Available Since 1.8.0	An optional password FusionAuth will use to authenticate with the SMTP server.
tenants`[x]`.emailConfiguration.port [Integer] Required Available Since 1.8.0	The port of the SMTP server that FusionAuth will use.
tenants`[x]`.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.
tenants`[x]`.emailConfiguration.security String Optional defaults to NONE Available Since 1.8.0	The type of security protocol FusionAuth will use when connecting to the SMTP server. The possible values are: `NONE` - no security will be used. All communications will be sent plaintext. `SSL` - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports. `TLS` - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.
tenants`[x]`.emailConfiguration.username [String] Optional Available Since 1.8.0	An optional username FusionAuth will to authenticate with the SMTP server.
tenants`[x]`.emailConfiguration.verificationEmailTemplateId [UUID] Optional	The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the `verifyEmail` field is `true` this field is required.
tenants`[x]`.emailConfiguration.verifyEmail [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the registers with your application.
tenants`[x]`.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the user changes them.
tenants`[x]`.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.8.0	The duration of the User Action. This value along with the `actionDurationUnit` will be used to set the duration of the User Action.
tenants`[x]`.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.8.0	The unit of time associated with a duration. The possible values are: `MINUTES` `HOURS` `DAYS` `WEEKS` `MONTHS` `YEARS`
tenants`[x]`.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.8.0	The length of time in seconds before the failed authentication count will be reset. For example, if `tooManyAttempts` is set to `5` and you fail to authenticate `4` times in a row, waiting for the duration specified here will cause your fifth attempt to start back at `1`.
tenants`[x]`.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.8.0	The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.
tenants`[x]`.failedAuthenticationConfiguration.userActionId [UUID] Available Since 1.8.0	The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
tenants`[x]`.id [UUID]	The unique Id of the Tenant.
tenants`[x]`.maximumPasswordAge.days [Integer] Available Since 1.8.0	The password maximum age in days. The number of days after which FusionAuth will require a user to change their password.
tenants`[x]`.maximumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the maximum password age is enabled and being enforced.
tenants`[x]`.minimumPasswordAge.seconds [Integer] Available Since 1.8.0	The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age.
tenants`[x]`.minimumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the minimum password age is enabled and being enforced.
tenants`[x]`.name [String]	The name of the Tenant.
tenants`[x]`.passwordEncryptionConfiguration.encryptionScheme [String] Available Since 1.8.0	The selected default encryption scheme.
tenants`[x]`.passwordEncryptionConfiguration.encryptionSchemeFactor [Integer] Available Since 1.8.0	The factor used by the password encryption scheme. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the `PasswordEncryptor` implementation.
tenants`[x]`.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Available Since 1.8.0	When enabled a user’s hash configuration will be modified to match these configured settings.

Example Response JSON

{
  "tenants": [
    {
      "data": {
        "description": "No more secrets, Marty."
      },
      "emailConfiguration": {
        "forgotPasswordEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
        "host": "smtp.sendgrid.net",
        "password": "password",
        "passwordlessEmailTemplateId": "a917e23a-da58-4cda-be01-90f542f8c343",
        "port": 587,
        "security": "TLS",
        "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
        "username": "username",
        "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87ab5",
        "verifyEmail": true,
        "verifyEmailWhenChanged": true
      },
      "externalIdentifierConfiguration": {
        "authorizationGrantIdTimeToLiveInSeconds": 30,
        "changePasswordIdTimeToLiveInSeconds": 600,
        "emailVerificationIdTimeToLiveInSeconds": 86400,
        "oneTimePasswordTimeToLiveInSeconds": 60,
        "passwordlessLoginTimeToLiveInSeconds": 180,
        "registrationVerificationIdTimeToLiveInSeconds": 86400,
        "setupPasswordIdTimeToLiveInSeconds": 86400,
        "twoFactorIdTimeToLiveInSeconds": 300,
        "twoFactorTrustIdTimeToLiveInSeconds": 2592000
      },
      "failedAuthenticationConfiguration": {
        "actionDuration": 3,
        "actionDurationUnit": "MINUTES",
        "resetCountInSeconds": 60,
        "tooManyAttempts": 5,
        "userActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4"
      },
      "id": "2321c2ab-0848-45fc-995b-869ba82c2a8c",
      "maximumPasswordAge": {
        "days": 180,
        "enabled": false
      },
      "minimumPasswordAge": {
        "enabled": false,
        "seconds": 30
      },
      "name": "Playtronics Co.",
      "passwordEncryptionConfiguration": {
        "encryptionScheme": "salted-pbkdf2-hmac-sha256",
        "encryptionSchemeFactor": 24000,
        "modifyEncryptionSchemeOnLogin": false
      }
    }
  ]
}

4. Update a Tenant

This API is used to update an existing Tenant. You must specify the Id of the Tenant you are updating on the URI. You must specify all of the properties of the Tenant when calling this API. This API does not merge the existing Tenant and your new data. It replaces the existing Tenant with your new data.

4.1. Request

Update the Tenant with the given Id

URI

PUT /api/tenant/{tenantId}

Table 9. Request Parameters
tenantId [UUID] Required	The Id of the Tenant to update.

Table 10. Request Body
tenant.data [Object] Optional	An object that can hold any information about the Tenant that should be persisted.
tenant.emailConfiguration.enabled [Boolean] Optional Deprecated	When this value is set to true the email configuration provided by this tenant will take precedence over the configuration by the System Configuration. Removed in version 1.8.0 In version 1.8.0 and beyond, a Tenant’s email configuration is enabled upon configuration.
tenant.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user is sent a forgot password email.
tenant.emailConfiguration.host [String] Required Available Since 1.8.0	The host name of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.password [String] Optional Available Since 1.8.0	An optional password FusionAuth will use to authenticate with the SMTP server.
tenant.emailConfiguration.port [Integer] Required Available Since 1.8.0	The port of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.
tenant.emailConfiguration.security String Optional defaults to NONE Available Since 1.8.0	The type of security protocol FusionAuth will use when connecting to the SMTP server. The possible values are: `NONE` - no security will be used. All communications will be sent plaintext. `SSL` - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports. `TLS` - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.
tenant.emailConfiguration.username [String] Optional Available Since 1.8.0	An optional username FusionAuth will to authenticate with the SMTP server.
tenant.emailConfiguration.verificationEmailTemplateId [UUID] Optional	The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the `verifyEmail` field is `true` this field is required.
tenant.emailConfiguration.verifyEmail [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the registers with your application.
tenant.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the user changes them.
tenant.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint. Value must be greater than 0 and less than or equal to 600.
tenant.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.oneTimePasswordTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a One Time Password is no longer valid and cannot be used by the Login API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.passwordlessLoginTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a passwordless code is no longer valid and cannot be used by the Passwordless API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Required Available Since 1.8.0	The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt. Value must be greater than 0.
tenant.failedAuthenticationConfiguration.actionDuration [Long] Optional defaults to `3` Available Since 1.8.0	The duration of the User Action. This value along with the `actionDurationUnit` will be used to set the duration of the User Action.
tenant.failedAuthenticationConfiguration.actionDurationUnit [String] Optional defaults to `"MINUTES"` Available Since 1.8.0	The unit of time associated with a duration. The possible values are: `MINUTES` `HOURS` `DAYS` `WEEKS` `MONTHS` `YEARS`
tenant.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Optional defaults to `60` Available Since 1.8.0	The length of time in seconds before the failed authentication count will be reset. For example, if `tooManyAttempts` is set to `5` and you fail to authenticate `4` times in a row, waiting for the duration specified here will cause your fifth attempt to start back at `1`.
tenant.failedAuthenticationConfiguration.tooManyAttempts [Integer] Optional defaults to `5` Available Since 1.8.0	The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.
tenant.failedAuthenticationConfiguration.userActionId [UUID] Optional Available Since 1.8.0	The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
tenant.maximumPasswordAge.days [Integer] Optional defaults to `180` Available Since 1.8.0	The password maximum age in days. The number of days after which FusionAuth will require a user to change their password. Required when `systemConfiguration.maximumPasswordAge.enabled` is set to `true`.
tenant.maximumPasswordAge.enabled [Boolean] Optional defaults to `false` Available Since 1.8.0	Indicates that the maximum password age is enabled and being enforced.
tenant.minimumPasswordAge.seconds [Integer] Optional defaults to `30` Available Since 1.8.0	The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age. Required when `systemConfiguration.minimumPasswordAge.enabled` is set to `true`.
tenant.minimumPasswordAge.enabled [Boolean] Optional defaults to `false` Available Since 1.8.0	Indicates that the minimum password age is enabled and being enforced.
tenant.name [String] Required	The name of the Tenant.
tenant.passwordEncryptionConfiguration.encryptionScheme [String] Optional defaults to `"salted-pbkdf2-hmac-sha256"` Available Since 1.8.0	The default method for encrypting the User’s password. The following encryptors are provided with FusionAuth: `salted-md5` `salted-sha256` `salted-hmac-sha256` `salted-pbkdf2-hmac-sha256` `bcrypt`
tenant.passwordEncryptionConfiguration.encryptionSchemeFactor [Integer] Optional defaults to `24000` Available Since 1.8.0	The factor used by the password encryption scheme. If not provided, the `PasswordEncryptor` provides a default value. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the `PasswordEncryptor` implementation.
tenant.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Optional defaults to `false` Available Since 1.8.0	When enabled a user’s hash configuration will be modified to match these configured settings. This can be useful to increase a password hash strength over time or upgrade imported users to a more secure encryption scheme after an initial import.

Example Request JSON

{
  "tenant": {
    "data": {
      "description": "No more secrets, Marty."
    },
    "emailConfiguration": {
      "forgotPasswordEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
      "host": "smtp.sendgrid.net",
      "password": "password",
      "passwordlessEmailTemplateId": "a917e23a-da58-4cda-be01-90f542f8c343",
      "port": 587,
      "security": "TLS",
      "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
      "username": "username",
      "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87ab5",
      "verifyEmail": true,
      "verifyEmailWhenChanged": true
    },
    "externalIdentifierConfiguration": {
      "authorizationGrantIdTimeToLiveInSeconds": 30,
      "changePasswordIdTimeToLiveInSeconds": 600,
      "emailVerificationIdTimeToLiveInSeconds": 86400,
      "oneTimePasswordTimeToLiveInSeconds": 60,
      "passwordlessLoginTimeToLiveInSeconds": 180,
      "registrationVerificationIdTimeToLiveInSeconds": 86400,
      "setupPasswordIdTimeToLiveInSeconds": 86400,
      "twoFactorIdTimeToLiveInSeconds": 300,
      "twoFactorTrustIdTimeToLiveInSeconds": 2592000
    },
    "failedAuthenticationConfiguration": {
      "actionDuration": 3,
      "actionDurationUnit": "MINUTES",
      "resetCountInSeconds": 60,
      "tooManyAttempts": 5,
      "userActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4"
    },
    "maximumPasswordAge": {
      "days": 180,
      "enabled": false
    },
    "minimumPasswordAge": {
      "enabled": false,
      "seconds": 30
    },
    "name": "Playtronics Co.",
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    }
  }
}

4.2. Response

The response for this API contains the Tenant that was updated.

Table 11. 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.
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 updated 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.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Table 12. Response Body
tenant.data [Object]	An object that can hold any information about the Tenant that should be persisted.
tenant.emailConfiguration.enabled [Boolean] Optional Deprecated	When this value is set to true the email configuration provided by this tenant will take precedence over the configuration by the System Configuration. Removed in version 1.8.0 In version 1.8.0 and beyond, a Tenant’s email configuration is enabled upon configuration.
tenant.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Optional	The Id of the Email Template that is used when a user is sent a forgot password email.
tenant.emailConfiguration.host [String] Required Available Since 1.8.0	The host name of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.password [String] Optional Available Since 1.8.0	An optional password FusionAuth will use to authenticate with the SMTP server.
tenant.emailConfiguration.port [Integer] Required Available Since 1.8.0	The port of the SMTP server that FusionAuth will use.
tenant.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional Available Since 1.8.0	The Id of the Email Template that is used when a user had their account created for them and they must set their password manually and they are sent an email to set their password.
tenant.emailConfiguration.security String Optional defaults to NONE Available Since 1.8.0	The type of security protocol FusionAuth will use when connecting to the SMTP server. The possible values are: `NONE` - no security will be used. All communications will be sent plaintext. `SSL` - SSL will be used to connect to the SMTP server. This protocol is not recommended unless it is the only one your SMTP server supports. `TLS` - TLS will be used to connect to the SMTP server. This is the preferred protocol for all SMTP servers.
tenant.emailConfiguration.username [String] Optional Available Since 1.8.0	An optional username FusionAuth will to authenticate with the SMTP server.
tenant.emailConfiguration.verificationEmailTemplateId [UUID] Optional	The If of the Email Template that is used to send the verification emails to users. These emails are used to verify that a user’s email address is valid. If the `verifyEmail` field is `true` this field is required.
tenant.emailConfiguration.verifyEmail [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the registers with your application.
tenant.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to `false`	Whether the user’s email addresses are verified when the user changes them.
tenant.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a OAuth authorization code in no longer valid to be exchanged for an access token. This is essentially the time allowed between the start of an Authorization request during the Authorization code grant and when you request an access token using this authorization code on the Token endpoint.
tenant.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.
tenant.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.
tenant.externalIdentifierConfiguration.passwordlessLoginTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a passwordless code is no longer valid and cannot be used by the Passwordless API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API. Value must be greater than 0.
tenant.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.
tenant.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.
tenant.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.
tenant.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Available Since 1.8.0	The time in seconds until an issued Two Factor trust Id is no longer valid and the User will be required to complete Two Factor authentication during the next authentication attempt.
tenant.failedAuthenticationConfiguration.actionDuration [Long] Available Since 1.8.0	The duration of the User Action. This value along with the `actionDurationUnit` will be used to set the duration of the User Action.
tenant.failedAuthenticationConfiguration.actionDurationUnit [String] Available Since 1.8.0	The unit of time associated with a duration. The possible values are: `MINUTES` `HOURS` `DAYS` `WEEKS` `MONTHS` `YEARS`
tenant.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Available Since 1.8.0	The length of time in seconds before the failed authentication count will be reset. For example, if `tooManyAttempts` is set to `5` and you fail to authenticate `4` times in a row, waiting for the duration specified here will cause your fifth attempt to start back at `1`.
tenant.failedAuthenticationConfiguration.tooManyAttempts [Integer] Available Since 1.8.0	The number of failed attempts considered to be too many. Once this threshold is reached the specified User Action will be applied to the user for the duration specified.
tenant.failedAuthenticationConfiguration.userActionId [UUID] Available Since 1.8.0	The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
tenant.maximumPasswordAge.days [Integer] Available Since 1.8.0	The password maximum age in days. The number of days after which FusionAuth will require a user to change their password.
tenant.maximumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the maximum password age is enabled and being enforced.
tenant.minimumPasswordAge.seconds [Integer] Available Since 1.8.0	The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age.
tenant.minimumPasswordAge.enabled [Boolean] Available Since 1.8.0	Indicates that the minimum password age is enabled and being enforced.
tenant.id [UUID]	The unique Id of the Tenant.
tenant.name [String]	The name of the Tenant.
tenant.passwordEncryptionConfiguration.encryptionScheme [String] Available Since 1.8.0	The selected default encryption scheme.
tenant.passwordEncryptionConfiguration.encryptionSchemeFactor [Integer] Available Since 1.8.0	The factor used by the password encryption scheme. Generally this will be used as an iteration count to generate the hash. The actual use of this value is up to the `PasswordEncryptor` implementation.
tenant.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Available Since 1.8.0	When enabled a user’s hash configuration will be modified to match these configured settings.

Example Response JSON

{
  "tenant": {
    "data": {
      "description": "No more secrets, Marty."
    },
    "emailConfiguration": {
      "forgotPasswordEmailTemplateId": "49aba1de-0225-45d7-a2b1-f9fe46b0242c",
      "host": "smtp.sendgrid.net",
      "password": "password",
      "passwordlessEmailTemplateId": "a917e23a-da58-4cda-be01-90f542f8c343",
      "port": 587,
      "security": "TLS",
      "setPasswordEmailTemplateId": "a9aba13e-0125-4fd7-a2b1-aaa146b02423",
      "username": "username",
      "verificationEmailTemplateId": "8da42c09-461c-45f3-b931-6e9f63b87ab5",
      "verifyEmail": true,
      "verifyEmailWhenChanged": true
    },
    "externalIdentifierConfiguration": {
      "authorizationGrantIdTimeToLiveInSeconds": 30,
      "changePasswordIdTimeToLiveInSeconds": 600,
      "emailVerificationIdTimeToLiveInSeconds": 86400,
      "oneTimePasswordTimeToLiveInSeconds": 60,
      "passwordlessLoginTimeToLiveInSeconds": 180,
      "registrationVerificationIdTimeToLiveInSeconds": 86400,
      "setupPasswordIdTimeToLiveInSeconds": 86400,
      "twoFactorIdTimeToLiveInSeconds": 300,
      "twoFactorTrustIdTimeToLiveInSeconds": 2592000
    },
    "failedAuthenticationConfiguration": {
      "actionDuration": 3,
      "actionDurationUnit": "MINUTES",
      "resetCountInSeconds": 60,
      "tooManyAttempts": 5,
      "userActionId": "16cfc707-268c-4c5b-8989-f71f3ee156d4"
    },
    "id": "2321c2ab-0848-45fc-995b-869ba82c2a8c",
    "maximumPasswordAge": {
      "days": 180,
      "enabled": false
    },
    "minimumPasswordAge": {
      "enabled": false,
      "seconds": 30
    },
    "name": "Playtronics Co.",
    "passwordEncryptionConfiguration": {
      "encryptionScheme": "salted-pbkdf2-hmac-sha256",
      "encryptionSchemeFactor": 24000,
      "modifyEncryptionSchemeOnLogin": false
    }
  }
}

5. Delete a Tenant

This API is used to permanently delete a Tenant. Deleting a Tenant will delete all Users, Applications and Groups that belong to this tenant. Proceed with caution.

5.1. Request

Delete a Tenant by Id

URI

DELETE /api/tenant/{tenantId}

Table 13. Request Parameters
tenantId [UUID] Required	The unique Id of the Tenant to delete.

5.2. Response

This API does not return a JSON response body.

Table 14. Response Codes
Code	Description
200	The request was successful. The response will be empty.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors.
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 delete 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.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.