Pre 1.30 System APIs
Overview
This page contains the APIs that are used for retrieving and updating the system configuration.
System Configuration
System Tools
System Status
Retrieve the System Configuration
This API is used to retrieve the System Configuration.
Request
Retrieve the System Configuration
GET /api/system-configuration
Response
The response for this API contains the System Configuration.
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
- systemConfiguration.auditLogConfiguration.delete.enabled [Boolean] Available since 1.7.0
-
Whether or not FusionAuth should delete the Audit Log based upon this configuration. When
true
the auditLogConfiguration.delete.numberOfDaysToRetain will be used to identify audit logs that are eligible for deletion. When this value is set tofalse
audit logs will be preserved forever. - systemConfiguration.auditLogConfiguration.delete.numberOfDaysToRetain [Integer] Available since 1.7.0
-
The number of days to retain the Audit Log.
- systemConfiguration.corsConfiguration.allowCredentials [Boolean] Available since 1.8.0
-
The
Access-Control-Allow-Credentials
response header values as described by MDN Access-Control-Allow-Credentials. - systemConfiguration.corsConfiguration.allowedHeaders [Array<String>] Available since 1.8.0
-
The
Access-Control-Allow-Headers
response header values as described by MDN Access-Control-Allow-Headers. - systemConfiguration.corsConfiguration.allowedMethods [Array<String>] Available since 1.8.0
-
The
Access-Control-Allow-Methods
response header values as described by MDN Access-Control-Allow-Methods. The possible values are:-
GET
-
POST
-
PUT
-
DELETE
-
HEAD
-
OPTIONS
-
- systemConfiguration.corsConfiguration.allowedOrigins [Array<String>] Available since 1.8.0
-
The
Access-Control-Allow-Origin
response header values as described by MDN Access-Control-Allow-Origin. If the wildcard*
is specified, no additional domains may be specified. - systemConfiguration.corsConfiguration.enabled [Boolean] Available since 1.8.0
-
Whether the FusionAuth CORS filter will process requests made to FusionAuth.
- systemConfiguration.corsConfiguration.exposedHeaders [Array<String>] Available since 1.8.0
-
The
Access-Control-Expose-Headers
response header values as described by MDN Access-Control-Expose-Headers. - systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds [Integer] Available since 1.8.0
-
The
Access-Control-Max-Age
response header values as described by MDN Access-Control-Max-Age. - systemConfiguration.data [Object] Available since 1.8.0
-
An object that can hold any information about the System that should be persisted.
- systemConfiguration.corsConfiguration.debug [Boolean] Available since 1.25.0
-
Whether or not FusionAuth will log debug messages to the event log. This is primarily useful for identifying why the FusionAuth CORS filter is rejecting a request and returning an HTTP response status code of
403
. - systemConfiguration.emailConfiguration.enabled [Boolean] Deprecated
-
Indicates that the SMTP email configuration is available for use by FusionAuth.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.host [String] Deprecated
-
The host name of the SMTP server that FusionAuth will use.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Deprecated
-
The Id of the Email Template that is used when a user is sent a forgot password email.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.password [String] Deprecated
-
An optional password FusionAuth will use to authenticate with the SMTP server.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.port [Integer] Deprecated
-
The port of the SMTP server that FusionAuth will use.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.security [String] Deprecated
-
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.Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
.
-
- systemConfiguration.emailConfiguration.setPasswordEmailTemplateId [UUID] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.username [String] Deprecated
-
An optional username FusionAuth will to authenticate with the SMTP server.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verificationEmailTemplateId [UUID] Deprecated
-
The Id 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 istrue
this field is required.Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verifyEmail [Boolean] Deprecated
-
Whether or not user’s email addresses are verified when the register with your application.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verifyEmailWhenChanged [Boolean] Deprecated
-
Whether or not user’s email addresses are verified when the user changes them.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.eventConfiguration.events [Object] Deprecated
-
A mapping of the configuration for each event type that FusionAuth sends. The event types that are the keys into this Object are:
-
user.action
- When a user action is triggered -
user.bulk.create
- When multiple users are created in bulk (i.e. during an import) -
user.create
- When a user is created -
user.email.verified
- When a user verifies their email address Available since 1.8.0 -
user.update
- When a user is updated -
user.deactivate
- When a user is deactivated -
user.reactivate
- When a user is reactivated -
user.login.success
- When a user completes a login request Available since 1.6.0 -
user.login.failed
- When a user fails a login request Available since 1.6.0 -
user.password.breach
- When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0 -
user.registration.create
- When a user registration is created Available since 1.6.0 -
user.registration.update
- When a user registration is updated Available since 1.6.0 -
user.registration.delete
- When a user registration is deleted Available since 1.6.0 -
user.registration.verified
- When a user completes registration verification Available since 1.8.0 -
user.delete
- When a user is deleted -
jwt.public-key.update
- When a JWT RSA Public / Private keypair may have been changed -
jwt.refresh
- When an access token is refreshed using a refresh token Available since 1.16.0 -
jwt.refresh-token.revoke
- When a JWT Refresh Token is revokedRemoved in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
.
-
- systemConfiguration.eventConfiguration.events
[type]
.enabled [Boolean] Deprecated -
Whether or not FusionAuth should send these types of events to any configured Webhooks.
Removed in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
. - systemConfiguration.eventConfiguration.events
[type]
.transactionType [String] Deprecated -
The transaction type that FusionAuth uses when sending these types of events to any configured Webhooks. The transaction types are:
-
None
- No Webhooks are required to succeed for the FusionAuth transaction to be committed. -
Any
- Only a single Webhook is required to succeed for the FusionAuth transaction to be committed. -
SimpleMajority
- A simple majority (50% or more) of Webhooks are required to succeed for the FusionAuth transaction to be committed. -
SuperMajority
- A super majority (2/3 or more) of Webhooks are required to succeed for the FusionAuth transaction to be committed. -
AbsoluteMajority
- Every Webhook must succeed for the FusionAuth transaction to be committed.Removed in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
.
-
- systemConfiguration.eventLogConfiguration.numberToRetain [Integer] Available since 1.7.0
-
The number of events to retain. Once the the number of event logs exceeds this configured value they will be deleted starting with the oldest event logs.
- systemConfiguration.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.actionDuration [Long] Deprecated
-
The duration of the User Action. This value along with the
actionDurationUnit
will be used to set the duration of the User Action.Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.actionDurationUnit [String] Deprecated
-
The unit of time associated with a duration. The possible values are:
-
MINUTES
-
HOURS
-
DAYS
-
WEEKS
-
MONTHS
-
YEARS
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
.
-
- systemConfiguration.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Deprecated
-
The length of time in seconds before the failed authentication count will be reset.
For example, if
tooManyAttempts
is set to5
and you fail to authenticate4
times in a row, waiting for the duration specified here will cause your fifth attempt to start back at1
.Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.tooManyAttempts [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.userActionId [UUID] Deprecated
-
The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.httpSessionMaxInactiveInterval [Integer] Deprecated
-
The time in seconds until an inactive session will be invalidated. Used when creating a new session in the FusionAuth OAuth front-end.
Removed in version 1.8.0
In version 1.8.0 and beyond, http session max inactive interval is managed per
Tenant
. - systemConfiguration.issuer [String] Available since 1.6.0 Deprecated
-
The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name. This is also used as the default issuer value when generating
Keys
.For example,
fusionauth.io
.Removed in version 1.8.0
In version 1.8.0 and beyond, issuer is managed per
Tenant
. - systemConfiguration.jwtConfiguration.accessTokenKeyId [UUID] Available since 1.6.0 Deprecated
-
The Id of the signing key used to sign the access token.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.algorithm [String] Deprecated
-
The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.
-
ES256
- ECDSA using P-256 curve and SHA-256 Available since 1.4.0 -
ES384
- ECDSA using P-384 curve and SHA-384 Available since 1.4.0 -
ES512
- ECDSA using P-521 curve and SHA-512 Available since 1.4.0 -
HS256
- HMAC using SHA-256 -
HS384
- HMAC using SHA-384 -
HS512
- HMAC using SHA-512 -
RS256
- RSASSA-PKCS1-v1_5 using SHA-256 -
RS384
- RSASSA-PKCS1-v1_5 using SHA-384 -
RS512
- RSASSA-PKCS1-v1_5 using SHA-512Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster.
-
- systemConfiguration.jwtConfiguration.enabled [Boolean] Deprecated
-
This value will always be true. The JWT configuration may not be disabled for the System Configuration.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.idTokenKeyId [UUID] Available since 1.6.0 Deprecated
-
The Id of the signing key used to sign the Id token.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.issuer [String] Deprecated
-
The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name.
For example,
fusionauth.io
.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.privateKey [String] Deprecated
-
The private key used when an
RSA
signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.publicKey [String] Deprecated
-
The public key used when an
RSA
signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer] Deprecated
-
The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.secret [String] Deprecated
-
The secret used when an
HMAC
based signing algorithm has been selected. This secret is used to sign and verify JWTs.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.timeToLiveInSeconds [Integer] Deprecated
-
The length of time in seconds the JWT will live before it is expired. This value is used to calculate the
exp
(expiration) identity claim.Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.loginRecordConfiguration.delete.enabled [Boolean] Available since 1.7.0
-
Whether or not FusionAuth should delete the login records based upon this configuration. When
true
the loginRecordConfiguration.delete.numberOfDaysToRetain will be used to identify login records that are eligible for deletion. When this value is set tofalse
login records will be preserved forever. - systemConfiguration.loginRecordConfiguration.delete.numberOfDaysToRetain [Integer] Available since 1.7.0
-
The number of days to retain login records.
- systemConfiguration.logoutURL [String] Deprecated
-
The logout redirect URL when sending the user’s browser to the
/oauth2/logout
URI of the FusionAuth Front End. This value is only used when a logout URL is not defined in your Application.Removed in version 1.8.0
In version 1.8.0 and beyond, logoutURL is managed per
Tenant
. - systemConfiguration.maximumPasswordAge.days [Integer] Deprecated
-
The password maximum age in days. The number of days after which FusionAuth will require a user to change their password.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.maximumPasswordAge.enabled [Boolean] Deprecated
-
Indicates that the maximum password age is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.minimumPasswordAge.seconds [Integer] Deprecated
-
The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.minimumPasswordAge.enabled [Boolean] Deprecated
-
Indicates that the minimum password age is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.encryptionScheme [String] Deprecated
-
The selected default encryption scheme.
Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.encryptionSchemeFactor [String] Deprecated
-
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.Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Deprecated
-
When enabled a user’s hash configuration will be modified to match these configured settings.
Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordValidationRules.maxLength [Integer] Deprecated
-
The maximum number of characters that are allowed for user passwords.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.minLength [Integer] Deprecated
-
The minimum number of characters that are required for user passwords.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer] Deprecated
-
The number of previous passwords that should be remembered so they are not re-used by the User.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean] Deprecated
-
Indicates that the remember previous password validation is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireMixedCase [Boolean] Deprecated
-
Indicates that passwords require an uppercase and lowercase character to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean] Deprecated
-
Indicates that passwords require a non-alphanumeric character to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireNumber [Boolean] Deprecated
-
Indicates that passwords require at least one number to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.reportTimezone [String]
-
The time zone used to adjust the stored UTC time when generating reports. Since reports are usually rolled up hourly, this timezone will be used for demarcating the hours.
For example:
America/Denver
orUS/Mountain
- systemConfiguration.uiConfiguration.headerColor [String]
-
A hexadecimal color to override the default menu color in the user interface.
- systemConfiguration.uiConfiguration.loginTheme.emailComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/complete page. This page is used after a user has verified their email address by clicking the URL in the email. After FusionAuth has updated their user object to indicate that their email was verified, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailSend [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/send page. This page is used after a user has asked for the verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailVerify [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/verify page by clicking the URL from the verification email and the
verificationId
has expired. FusionAuth expiresverificationId
after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.enabled [Boolean] Deprecated
-
Indicates that the login theme is enabled and will be used to style the login pages.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.helpers [String] Deprecated
-
A FreeMarker template that contains all of the macros and templates used by the rest of the
loginTheme
FreeMarker templates (i.e.oauth2Authorize
). This allows you to configure the general layout of your UI configuration and login theme without having to copy and paste HTML into each of the templates.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2Authorize [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/authorize page. This is the main login page for FusionAuth and is used for all interactive OAuth and OpenId Connect workflows.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2Error [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/error page. This page is used if the user starts or is in the middle of the OAuth workflow and any type of error occurs. This could be caused by the user messing with the URL or internally some type of information wasn’t passed between the OAuth endpoints correctly. For example, if you are federating login to an external IdP and that IdP does not properly echo the
state
parameter, FusionAuth’s OAuth workflow will break and this page will be displayed.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2TwoFactor [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/two-factor page. This page is used if the user has two-factor authentication enabled and they need to type in their code again. FusionAuth will properly handle the SMS or authenticator app processing on the back end. This page contains the form that the user will put their code into.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordChange [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/change page. This page is used if the user is required to change their password or if they have requested a password reset. This page contains the form that allows the user to provide a new password.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/complete page. This page is used after the user has successfully updated their password (or reset it). This page should instruct the user that their password was updated and that they need to login again.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordForgot [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/forgot page. This page is used when a user starts the forgot password workflow. This page renders the form where the user types in their email address.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordSent [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/sent page. This page is used when a user has submitted the forgot password form with their email. FusionAuth does not indicate back to the user if their email address was valid in order to prevent malicious activity that could reveal valid email addresses. Therefore, this page should indicate to the user that if their email was valid, they will receive an email shortly with a link to reset their password.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/complete page. This page is used after a user has verified their email address for a specific application (i.e. a user registration) by clicking the URL in the email. After FusionAuth has updated their registration object to indicate that their email was verified, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationSend [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/send page. This page is used after a user has asked for the application specific verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationVerify [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/verify page by clicking the URL from the application specific verification email and the
verificationId
has expired. FusionAuth expiresverificationId
after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.stylesheet [String] Deprecated
-
A CSS stylesheet used to style the login page and other templates such as forgot password, and verify email.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.logoURL [String]
-
A URL of a logo to override the default FusionAuth logo in the user interface.
- systemConfiguration.uiConfiguration.menuFontColor [String]
-
A hexadecimal color to override the default menu font color in the user interface.
{
"systemConfiguration": {
"auditLogConfiguration": {
"delete": {
"enabled": true,
"numberOfDaysToRetain": 90
}
},
"corsConfiguration": {
"allowCredentials": true,
"allowedHeaders": [
"Accept",
"Access-Control-Request-Headers",
"Access-Control-Request-Method",
"Authorization",
"Content-Type",
"Last-Modified",
"Origin",
"X-FusionAuth-TenantId",
"X-Requested-With"
],
"allowedMethods": [
"GET",
"POST",
"HEAD",
"OPTIONS",
"PUT",
"DELETE"
],
"allowedOrigins": [
"*"
],
"debug": false,
"enabled": true,
"exposedHeaders": [
"Access-Control-Allow-Origin",
"Access-Control-Allow-Credentials"
],
"preflightMaxAgeInSeconds": 1800
},
"eventLogConfiguration": {
"numberToRetain": 10000
},
"loginRecordConfiguration": {
"delete": {
"enabled": true,
"numberOfDaysToRetain": 90
}
},
"reportTimezone": "America/Denver",
"uiConfiguration": {
"headerColor": "303030",
"logoURL": "https://local.fusionauth.io/images/logo.svg",
"menuFontColor": "F0F0F0"
}
}
}
Update the System Configuration
This API is used to update an existing System Configuration.
No Id is required to update this object.
You must specify all of the properties of the System Configuration when calling this API with the PUT
HTTP method. When used with PUT
, this API doesn’t merge the existing System Configuration and your new data. It replaces the existing System Configuration with your new data.
Utilize the PATCH
HTTP method to send specific changes to merge into an existing System Configuration.
Request
Update the System Configuration
PUT /api/system-configuration
PATCH /api/system-configuration
Available since 1.39.0
When using the PATCH method, you can either use the same request body documentation that is provided for the PUT request for backward compatibility. Or you may use either JSON Patch/RFC 6902 or JSON Merge Patch/RFC 7396. See the
PATCH
documentation for more information.Available since 1.12.0
When using the PATCH method, use the same request body documentation that is provided for the PUT request. The PATCH method will merge the provided request parameters into the existing object, this means all parameters are optional when using the PATCH method and you only provide the values you want changed. A
null
value can be used to remove a value. Patching anArray
will result in all values from the new list being appended to the existing list, this is a known limitation to the current implementation of PATCH.
Request Body
- systemConfiguration.auditLogConfiguration.delete.enabled [Boolean] Optional defaults to
false
Available since 1.7.0 -
Whether or not FusionAuth should delete the Audit Log based upon this configuration. When
true
the auditLogConfiguration.delete.numberOfDaysToRetain will be used to identify audit logs that are eligible for deletion. When this value is set tofalse
audit logs will be preserved forever. - systemConfiguration.auditLogConfiguration.delete.numberOfDaysToRetain [Integer] Optional defaults to
365
Available since 1.7.0 -
The number of days to retain the Audit Log. Required when auditLogConfiguration.delete.enabled is set to
true
. - systemConfiguration.corsConfiguration.allowCredentials [Boolean] Optional defaults to
false
Available since 1.8.0 -
The
Access-Control-Allow-Credentials
response header values as described by MDN Access-Control-Allow-Credentials. - systemConfiguration.corsConfiguration.allowedHeaders [Array<String>] Optional Available since 1.8.0
-
The
Access-Control-Allow-Headers
response header values as described by MDN Access-Control-Allow-Headers. - systemConfiguration.corsConfiguration.allowedMethods [Array<String>] Optional Available since 1.8.0
-
The
Access-Control-Allow-Methods
response header values as described by MDN Access-Control-Allow-Methods. - systemConfiguration.corsConfiguration.allowedOrigins [Array<String>] Optional Available since 1.8.0
-
The
Access-Control-Allow-Origin
response header values as described by MDN Access-Control-Allow-Origin. If the wildcard*
is specified, no additional domains may be specified. - systemConfiguration.corsConfiguration.debug [Boolean] Optional defaults to
false
Available since 1.25.0 -
Whether or not FusionAuth will log debug messages to the event log. This is primarily useful for identifying why the FusionAuth CORS filter is rejecting a request and returning an HTTP response status code of
403
. - systemConfiguration.corsConfiguration.enabled [Boolean] Optional defaults to
false
Available since 1.8.0 -
Whether the FusionAuth CORS filter will process requests made to FusionAuth.
- systemConfiguration.corsConfiguration.exposedHeaders [Array<String>] Optional Available since 1.8.0
-
The
Access-Control-Expose-Headers
response header values as described by MDN Access-Control-Expose-Headers. - systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds [Integer] Optional Available since 1.8.0
-
The
Access-Control-Max-Age
response header values as described by MDN Access-Control-Max-Age. - systemConfiguration.emailConfiguration.enabled Optional [Boolean] defaults to
false
Deprecated -
Indicates that the SMTP email configuration is available for use by FusionAuth.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Required Deprecated
-
The Id of the Email Template that is used when a user is sent a forgot password email.
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.host [String] Optional Deprecated
-
The host name of the SMTP server that FusionAuth will use. Required when
systemConfiguration.emailConfiguration.enabled
is set totrue
.In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.password [String] Optional Deprecated
-
An optional password FusionAuth will use to authenticate with the SMTP server.
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.port [Integer] Optional Deprecated
-
The port of the SMTP server that FusionAuth will use. Required when
systemConfiguration.emailConfiguration.enabled
is set totrue
.In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.setPasswordEmailTemplateId [UUID] Optional Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.security [String] Optional defaults to NONE Deprecated
-
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.Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
.
-
- systemConfiguration.emailConfiguration.username [String] Optional Deprecated
-
An optional username FusionAuth will to authenticate with the SMTP server.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verificationEmailTemplateId [UUID] Optional Deprecated
-
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 istrue
this field is required.Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verifyEmail [Boolean] Optional defaults to
false
Deprecated -
Whether or not user’s email addresses are verified when the register with your application.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verifyEmailWhenChanged [Boolean] Optional defaults to
false
Deprecated -
Whether or not user’s email addresses are verified when the user changes them.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.eventConfiguration.events [Object] Optional defaults to {} Deprecated
-
A mapping of the configuration for each event type that FusionAuth sends. The event types that are the keys into this Object are:
-
user.action
- When a user action is triggered -
user.bulk.create
- When multiple users are created in bulk (i.e. during an import) -
user.create
- When a user is created -
user.email.verified
- When a user verifies their email address Available since 1.8.0 -
user.update
- When a user is updated -
user.deactivate
- When a user is deactivated -
user.reactivate
- When a user is reactivated -
user.login.success
- When a user completes a login request Available since 1.6.0 -
user.login.failed
- When a user fails a login request Available since 1.6.0 -
user.password.breach
- When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0 -
user.registration.create
- When a user registration is created Available since 1.6.0 -
user.registration.update
- When a user registration is updated Available since 1.6.0 -
user.registration.delete
- When a user registration is deleted Available since 1.6.0 -
user.registration.verified
- When a user completes registration verification Available since 1.8.0 -
user.delete
- When a user is deleted -
jwt.public-key.update
- When a JWT RSA Public / Private keypair may have been changed -
jwt.refresh
- When an access token is refreshed using a refresh token Available since 1.16.0 -
jwt.refresh-token.revoke
- When a JWT Refresh Token is revokedRemoved in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
.
-
- systemConfiguration.eventConfiguration.events
[type]
.enabled [Boolean] Optional defaults tofalse
Deprecated -
Whether or not FusionAuth should send these types of events to any configured Webhooks.
Removed in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
. - systemConfiguration.eventConfiguration.events
[type]
.transactionType [String] Optional Deprecated -
The transaction type that FusionAuth uses when sending these types of events to any configured Webhooks. The transaction types are:
-
None
- No Webhooks are required to succeed for the FusionAuth transaction to be committed. -
Any
- Only a single Webhook is required to succeed for the FusionAuth transaction to be committed. -
SimpleMajority
- A simple majority (50% or more) of Webhooks are required to succeed for the FusionAuth transaction to be committed. -
SuperMajority
- A super majority (2/3 or more) of Webhooks are required to succeed for the FusionAuth transaction to be committed. -
AbsoluteMajority
- Every Webhook must succeed for the FusionAuth transaction to be committed.Removed in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
.
-
- systemConfiguration.eventLogConfiguration.numberToRetain [Integer] Optional defaults to
10,000
Available since 1.7.0 -
The number of events to retain. Once the the number of event logs exceeds this configured value they will be deleted starting with the oldest event logs.
- systemConfiguration.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Required Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.actionDuration [Long] Deprecated
-
The duration of the User Action. This value along with the
actionDurationUnit
will be used to set the duration of the User Action.Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.actionDurationUnit [String] Deprecated
-
The unit of time associated with a duration. The possible values are:
-
MINUTES
-
HOURS
-
DAYS
-
WEEKS
-
MONTHS
-
YEARS
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
.
-
- systemConfiguration.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Deprecated
-
The length of time in seconds before the failed authentication count will be reset.
For example, if
tooManyAttempts
is set to5
and you fail to authenticate4
times in a row, waiting for the duration specified here will cause your fifth attempt to start back at1
.Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.tooManyAttempts [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.userActionId [UUID] Deprecated
-
The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.httpSessionMaxInactiveInterval [Integer] Required defaults to
60 minutes
Deprecated -
The time in seconds until an inactive session will be invalidated. Used when creating a new session in the FusionAuth Front End.
In version 1.8.0 and beyond, http session max inactive interval is managed per
Tenant
. - systemConfiguration.issuer [String] Required Available since 1.6.0 Deprecated
-
The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name. This is also used as the default issuer value when generating
Keys
.For example,
fusionauth.io
.Removed in version 1.8.0
In version 1.8.0 and beyond, issuer is managed per
Tenant
. - systemConfiguration.jwtConfiguration.accessTokenKeyId [UUID] Required Available since 1.6.0 Deprecated
-
The Id of the signing key used to sign the access token.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.algorithm [String] Required Deprecated
-
The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.
-
ES256
- ECDSA using P-256 curve and SHA-256 Available since 1.4.0 -
ES384
- ECDSA using P-384 curve and SHA-384 Available since 1.4.0 -
ES512
- ECDSA using P-521 curve and SHA-512 Available since 1.4.0 -
HS256
- HMAC using SHA-256 -
HS384
- HMAC using SHA-384 -
HS512
- HMAC using SHA-512 -
RS256
- RSASSA-PKCS1-v1_5 using SHA-256 -
RS384
- RSASSA-PKCS1-v1_5 using SHA-384 -
RS512
- RSASSA-PKCS1-v1_5 using SHA-512Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster.
-
- systemConfiguration.jwtConfiguration.idTokenKeyId [UUID] Required Available since 1.6.0 Deprecated
-
The Id of the signing key used to sign the Id token.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.issuer [String] Required Deprecated
-
The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name.
For example,
fusionauth.io
.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.privateKey [String] Optional Deprecated
-
The private key used when an
RSA
signing algorithm has been selected. The private key will be used to sign the JWT. This key is expected to be in a PEM encoded format. Required whenalgorithm
is set to an RSA based value.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.publicKey [String] Optional Deprecated
-
The public key used when an
RSA
signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key is expected to be in a PEM encoded format. Required whenalgorithm
is set to an RSA based value.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.refreshTokenTimeToLiveInMinutes Required [Integer] Deprecated
-
The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.secret [String] Optional Deprecated
-
The secret used when an
HMAC
based signing algorithm has been selected. This secret is used to sign and verify JWTs. Required whenalgorithm
is set to an HMAC based value.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.timeToLiveInSeconds [Integer] Required Deprecated
-
The length of time in seconds the JWT will live before it is expired. This value is used to calculate the
exp
(expiration) identity claim.Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.loginRecordConfiguration.delete.enabled [Boolean] Optional defaults to
false
Available since 1.7.0 -
Whether or not FusionAuth should delete the login records based upon this configuration. When
true
the loginRecordConfiguration.delete.numberOfDaysToRetain will be used to identify login records that are eligible for deletion. When this value is set tofalse
login records will be preserved forever. - systemConfiguration.loginRecordConfiguration.delete.numberOfDaysToRetain [Integer] Optional defaults to
365
Available since 1.7.0 -
The number of days to retain login records. Required when loginRecordConfiguration.delete.enabled is set to
true
. - systemConfiguration.logoutURL [String] Optional Deprecated
-
The logout redirect URL when sending the user’s browser to the
/oauth2/logout
URI of the FusionAuth Front End. This value is only used when a logout URL is not defined in your Application.Removed in version 1.8.0
In version 1.8.0 and beyond, logoutURL is managed per
Tenant
. - systemConfiguration.maximumPasswordAge.days [Integer] Optional Deprecated
-
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 totrue
.Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.maximumPasswordAge.enabled [Boolean] Optional Deprecated
-
Indicates that the maximum password age is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.minimumPasswordAge.seconds [Integer] Optional Deprecated
-
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 totrue
.Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.minimumPasswordAge.enabled [Boolean] Optional Deprecated
-
Indicates that the minimum password age is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.encryptionScheme [String] Optional Deprecated
-
The default method for encrypting the User’s password. The following encryptors are provided with FusionAuth:
-
salted-pbkdf2-hmac-sha256-512
Available since 1.34.0 -
Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
.
- systemConfiguration.passwordEncryptionConfiguration.encryptionSchemeFactor [String] Optional Deprecated
-
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 thePasswordEncryptor
implementation.Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Optional Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordValidationRules.maxLength [Integer] Required Deprecated
-
The maximum number of characters that are allowed for user passwords.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.minLength [Integer] Required Deprecated
-
The minimum number of characters that are required for user passwords.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer] Optional Deprecated
-
The number of previous passwords that should be remembered so they are not re-used by the User. Required when
systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count
is set totrue
.Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean] Optional Deprecated
-
Indicates that the remember previous password validation is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireMixedCase [Boolean] Optional defaults to
false
Deprecated -
Indicates that passwords require an uppercase and lowercase character to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean] Optional defaults to
false
Deprecated -
Indicates that passwords require a non-alphanumeric character to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireNumber [Boolean] Optional defaults to
false
Deprecated -
Indicates that passwords require at least one number to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.reportTimezone [String] Required
-
The time zone used to adjust the stored UTC time when generating reports. Since reports are usually rolled up hourly, this timezone will be used for demarcating the hours.
For example:
America/Denver
orUS/Mountain
- systemConfiguration.uiConfiguration.headerColor [String] Optional
-
A hexadecimal color to override the default menu color in the user interface.
Example:
000000
would set the menu color to black. - systemConfiguration.uiConfiguration.loginTheme.emailComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/complete page. This page is used after a user has verified their email address by clicking the URL in the email. After FusionAuth has updated their user object to indicate that their email was verified, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailSend [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/send page. This page is used after a user has asked for the verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailVerify [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/verify page by clicking the URL from the verification email and the
verificationId
has expired. FusionAuth expiresverificationId
after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.enabled [Boolean] Deprecated
-
Indicates that the login theme is enabled and will be used to style the login pages.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.helpers [String] Deprecated
-
A FreeMarker template that contains all of the macros and templates used by the rest of the
loginTheme
FreeMarker templates (i.e.oauth2Authorize
). This allows you to configure the general layout of your UI configuration and login theme without having to copy and paste HTML into each of the templates.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2Authorize [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/authorize page. This is the main login page for FusionAuth and is used for all interactive OAuth and OpenId Connect workflows.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2Error [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/error page. This page is used if the user starts or is in the middle of the OAuth workflow and any type of error occurs. This could be caused by the user messing with the URL or internally some type of information wasn’t passed between the OAuth endpoints correctly. For example, if you are federating login to an external IdP and that IdP does not properly echo the
state
parameter, FusionAuth’s OAuth workflow will break and this page will be displayed.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2TwoFactor [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/two-factor page. This page is used if the user has two-factor authentication enabled and they need to type in their code again. FusionAuth will properly handle the SMS or authenticator app processing on the back end. This page contains the form that the user will put their code into.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordChange [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/change page. This page is used if the user is required to change their password or if they have requested a password reset. This page contains the form that allows the user to provide a new password.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/complete page. This page is used after the user has successfully updated their password (or reset it). This page should instruct the user that their password was updated and that they need to login again.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordForgot [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/forgot page. This page is used when a user starts the forgot password workflow. This page renders the form where the user types in their email address.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordSent [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/sent page. This page is used when a user has submitted the forgot password form with their email. FusionAuth does not indicate back to the user if their email address was valid in order to prevent malicious activity that could reveal valid email addresses. Therefore, this page should indicate to the user that if their email was valid, they will receive an email shortly with a link to reset their password.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/complete page. This page is used after a user has verified their email address for a specific application (i.e. a user registration) by clicking the URL in the email. After FusionAuth has updated their registration object to indicate that their email was verified, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationSend [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/send page. This page is used after a user has asked for the application specific verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailVerify [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/verify page by clicking the URL from the application specific verification email and the
verificationId
has expired. FusionAuth expiresverificationId
after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.stylesheet [String] Deprecated
-
A CSS stylesheet used to style the login page and other templates such as forgot password, and verify email.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.logoURL [String] Optional
-
A URL of a logo to override the default FusionAuth logo in the user interface.
- systemConfiguration.uiConfiguration.menuFontColor [String] Optional
-
A hexadecimal color to override the default menu font color in the user interface.
Example:
FFFFFF
would set the menu font color to white.
{
"systemConfiguration": {
"auditLogConfiguration": {
"delete": {
"enabled": true,
"numberOfDaysToRetain": 90
}
},
"corsConfiguration": {
"allowCredentials": true,
"allowedHeaders": [
"Accept",
"Access-Control-Request-Headers",
"Access-Control-Request-Method",
"Authorization",
"Content-Type",
"Last-Modified",
"Origin",
"X-FusionAuth-TenantId",
"X-Requested-With"
],
"allowedMethods": [
"GET",
"POST",
"HEAD",
"OPTIONS",
"PUT",
"DELETE"
],
"allowedOrigins": [
"*"
],
"enabled": true,
"exposedHeaders": [
"Access-Control-Allow-Origin",
"Access-Control-Allow-Credentials"
],
"preflightMaxAgeInSeconds": 1800
},
"eventLogConfiguration": {
"numberToRetain": 10000
},
"loginRecordConfiguration": {
"delete": {
"enabled": true,
"numberOfDaysToRetain": 90
}
},
"reportTimezone": "America/Denver",
"uiConfiguration": {
"headerColor": "303030",
"logoURL": "https://local.fusionauth.io/images/logo.svg",
"menuFontColor": "F0F0F0"
}
}
}
Response
The response for this API contains the System Configuration.
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
- systemConfiguration.auditLogConfiguration.delete.enabled [Boolean] Available since 1.7.0
-
Whether or not FusionAuth should delete the Audit Log based upon this configuration. When
true
the auditLogConfiguration.delete.numberOfDaysToRetain will be used to identify audit logs that are eligible for deletion. When this value is set tofalse
audit logs will be preserved forever. - systemConfiguration.auditLogConfiguration.delete.numberOfDaysToRetain [Integer] Available since 1.7.0
-
The number of days to retain the Audit Log.
- systemConfiguration.corsConfiguration.allowCredentials [Boolean] Available since 1.8.0
-
The
Access-Control-Allow-Credentials
response header values as described by MDN Access-Control-Allow-Credentials. - systemConfiguration.corsConfiguration.allowedHeaders [Array<String>] Available since 1.8.0
-
The
Access-Control-Allow-Headers
response header values as described by MDN Access-Control-Allow-Headers. - systemConfiguration.corsConfiguration.allowedMethods [Array<String>] Available since 1.8.0
-
The
Access-Control-Allow-Methods
response header values as described by MDN Access-Control-Allow-Methods. The possible values are:-
GET
-
POST
-
PUT
-
DELETE
-
HEAD
-
OPTIONS
-
- systemConfiguration.corsConfiguration.allowedOrigins [Array<String>] Available since 1.8.0
-
The
Access-Control-Allow-Origin
response header values as described by MDN Access-Control-Allow-Origin. If the wildcard*
is specified, no additional domains may be specified. - systemConfiguration.corsConfiguration.enabled [Boolean] Available since 1.8.0
-
Whether the FusionAuth CORS filter will process requests made to FusionAuth.
- systemConfiguration.corsConfiguration.exposedHeaders [Array<String>] Available since 1.8.0
-
The
Access-Control-Expose-Headers
response header values as described by MDN Access-Control-Expose-Headers. - systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds [Integer] Available since 1.8.0
-
The
Access-Control-Max-Age
response header values as described by MDN Access-Control-Max-Age. - systemConfiguration.data [Object] Available since 1.8.0
-
An object that can hold any information about the System that should be persisted.
- systemConfiguration.corsConfiguration.debug [Boolean] Available since 1.25.0
-
Whether or not FusionAuth will log debug messages to the event log. This is primarily useful for identifying why the FusionAuth CORS filter is rejecting a request and returning an HTTP response status code of
403
. - systemConfiguration.emailConfiguration.enabled [Boolean] Deprecated
-
Indicates that the SMTP email configuration is available for use by FusionAuth.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.host [String] Deprecated
-
The host name of the SMTP server that FusionAuth will use.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.forgotPasswordEmailTemplateId [UUID] Deprecated
-
The Id of the Email Template that is used when a user is sent a forgot password email.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.password [String] Deprecated
-
An optional password FusionAuth will use to authenticate with the SMTP server.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.port [Integer] Deprecated
-
The port of the SMTP server that FusionAuth will use.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.security [String] Deprecated
-
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.Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
.
-
- systemConfiguration.emailConfiguration.setPasswordEmailTemplateId [UUID] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.username [String] Deprecated
-
An optional username FusionAuth will to authenticate with the SMTP server.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verificationEmailTemplateId [UUID] Deprecated
-
The Id 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 istrue
this field is required.Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verifyEmail [Boolean] Deprecated
-
Whether or not user’s email addresses are verified when the register with your application.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.emailConfiguration.verifyEmailWhenChanged [Boolean] Deprecated
-
Whether or not user’s email addresses are verified when the user changes them.
Removed in version 1.8.0
In version 1.8.0 and beyond, email configuration is managed per
Tenant
. - systemConfiguration.eventConfiguration.events [Object] Deprecated
-
A mapping of the configuration for each event type that FusionAuth sends. The event types that are the keys into this Object are:
-
user.action
- When a user action is triggered -
user.bulk.create
- When multiple users are created in bulk (i.e. during an import) -
user.create
- When a user is created -
user.email.verified
- When a user verifies their email address Available since 1.8.0 -
user.update
- When a user is updated -
user.deactivate
- When a user is deactivated -
user.reactivate
- When a user is reactivated -
user.login.success
- When a user completes a login request Available since 1.6.0 -
user.login.failed
- When a user fails a login request Available since 1.6.0 -
user.password.breach
- When Reactor detects a user is using a potentially breached password (requires an activated license) Available since 1.15.0 -
user.registration.create
- When a user registration is created Available since 1.6.0 -
user.registration.update
- When a user registration is updated Available since 1.6.0 -
user.registration.delete
- When a user registration is deleted Available since 1.6.0 -
user.registration.verified
- When a user completes registration verification Available since 1.8.0 -
user.delete
- When a user is deleted -
jwt.public-key.update
- When a JWT RSA Public / Private keypair may have been changed -
jwt.refresh
- When an access token is refreshed using a refresh token Available since 1.16.0 -
jwt.refresh-token.revoke
- When a JWT Refresh Token is revokedRemoved in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
.
-
- systemConfiguration.eventConfiguration.events
[type]
.enabled [Boolean] Deprecated -
Whether or not FusionAuth should send these types of events to any configured Webhooks.
Removed in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
. - systemConfiguration.eventConfiguration.events
[type]
.transactionType [String] Deprecated -
The transaction type that FusionAuth uses when sending these types of events to any configured Webhooks. The transaction types are:
-
None
- No Webhooks are required to succeed for the FusionAuth transaction to be committed. -
Any
- Only a single Webhook is required to succeed for the FusionAuth transaction to be committed. -
SimpleMajority
- A simple majority (50% or more) of Webhooks are required to succeed for the FusionAuth transaction to be committed. -
SuperMajority
- A super majority (2/3 or more) of Webhooks are required to succeed for the FusionAuth transaction to be committed. -
AbsoluteMajority
- Every Webhook must succeed for the FusionAuth transaction to be committed.Removed in version 1.8.0
In version 1.8.0 and beyond, event configuration is managed per
Tenant
.
-
- systemConfiguration.eventLogConfiguration.numberToRetain [Integer] Available since 1.7.0
-
The number of events to retain. Once the the number of event logs exceeds this configured value they will be deleted starting with the oldest event logs.
- systemConfiguration.externalIdentifierConfiguration.authorizationGrantIdTimeToLiveInSeconds [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.changePasswordIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a change password Id is no longer valid and cannot be used by the Change Password API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.emailVerificationIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a email verification Id is no longer valid and cannot be used by the Verify Email API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.registrationVerificationIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a registration verification Id is no longer valid and cannot be used by the Verify Registration API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.setupPasswordIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a setup password Id is no longer valid and cannot be used by the Change Password API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.twoFactorIdTimeToLiveInSeconds [Integer] Deprecated
-
The time in seconds until a two factor Id is no longer valid and cannot be used by the Two Factor Login API.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.externalIdentifierConfiguration.twoFactorTrustIdTimeToLiveInSeconds [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, external identifier configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.actionDuration [Long] Deprecated
-
The duration of the User Action. This value along with the
actionDurationUnit
will be used to set the duration of the User Action.Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.actionDurationUnit [String] Deprecated
-
The unit of time associated with a duration. The possible values are:
-
MINUTES
-
HOURS
-
DAYS
-
WEEKS
-
MONTHS
-
YEARS
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
.
-
- systemConfiguration.failedAuthenticationConfiguration.resetCountInSeconds [Integer] Deprecated
-
The length of time in seconds before the failed authentication count will be reset.
For example, if
tooManyAttempts
is set to5
and you fail to authenticate4
times in a row, waiting for the duration specified here will cause your fifth attempt to start back at1
.Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.tooManyAttempts [Integer] Deprecated
-
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.
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.failedAuthenticationConfiguration.userActionId [UUID] Deprecated
-
The Id of the User Action that is applied when the threshold is reached for too many failed authentication attempts.
Removed in version 1.8.0
In version 1.8.0 and beyond, failed authentication configuration is managed per
Tenant
. - systemConfiguration.httpSessionMaxInactiveInterval [Integer] Deprecated
-
The time in seconds until an inactive session will be invalidated. Used when creating a new session in the FusionAuth OAuth front-end.
Removed in version 1.8.0
In version 1.8.0 and beyond, http session max inactive interval is managed per
Tenant
. - systemConfiguration.issuer [String] Available since 1.6.0 Deprecated
-
The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name. This is also used as the default issuer value when generating
Keys
.For example,
fusionauth.io
.Removed in version 1.8.0
In version 1.8.0 and beyond, issuer is managed per
Tenant
. - systemConfiguration.jwtConfiguration.accessTokenKeyId [UUID] Available since 1.6.0 Deprecated
-
The Id of the signing key used to sign the access token.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.algorithm [String] Deprecated
-
The algorithm used to sign the JSON Web Token (JWT). The following available JSON Web Algorithms (JWA) as described in RFC 7518 are available.
-
ES256
- ECDSA using P-256 curve and SHA-256 Available since 1.4.0 -
ES384
- ECDSA using P-384 curve and SHA-384 Available since 1.4.0 -
ES512
- ECDSA using P-521 curve and SHA-512 Available since 1.4.0 -
HS256
- HMAC using SHA-256 -
HS384
- HMAC using SHA-384 -
HS512
- HMAC using SHA-512 -
RS256
- RSASSA-PKCS1-v1_5 using SHA-256 -
RS384
- RSASSA-PKCS1-v1_5 using SHA-384 -
RS512
- RSASSA-PKCS1-v1_5 using SHA-512Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster.
-
- systemConfiguration.jwtConfiguration.enabled [Boolean] Deprecated
-
This value will always be true. The JWT configuration may not be disabled for the System Configuration.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.idTokenKeyId [UUID] Available since 1.6.0 Deprecated
-
The Id of the signing key used to sign the Id token.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.issuer [String] Deprecated
-
The name or issuer of the JWT, this is generally something unique such as a fully qualified domain name.
For example,
fusionauth.io
.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.privateKey [String] Deprecated
-
The private key used when an
RSA
signing algorithm has been selected. The private key will be used to sign the JWT. This key will be returned in a PEM encoded format.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.publicKey [String] Deprecated
-
The public key used when an
RSA
signing algorithms has been selected. The public key will be used to verify JWTs signed with the private key. This key will be returned in a PEM encoded format.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.refreshTokenTimeToLiveInMinutes [Integer] Deprecated
-
The length of time in minutes the JWT refresh token will live before it is expired and is not able to be exchanged for a JWT.
Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.jwtConfiguration.secret [String] Deprecated
-
The secret used when an
HMAC
based signing algorithm has been selected. This secret is used to sign and verify JWTs.Removed in version 1.8.0
Removed in version 1.6.0 In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
and Keymaster. - systemConfiguration.jwtConfiguration.timeToLiveInSeconds [Integer] Deprecated
-
The length of time in seconds the JWT will live before it is expired. This value is used to calculate the
exp
(expiration) identity claim.Removed in version 1.8.0
In version 1.8.0 and beyond, JWT configuration is managed per
Tenant
. - systemConfiguration.loginRecordConfiguration.delete.enabled [Boolean] Available since 1.7.0
-
Whether or not FusionAuth should delete the login records based upon this configuration. When
true
the loginRecordConfiguration.delete.numberOfDaysToRetain will be used to identify login records that are eligible for deletion. When this value is set tofalse
login records will be preserved forever. - systemConfiguration.loginRecordConfiguration.delete.numberOfDaysToRetain [Integer] Available since 1.7.0
-
The number of days to retain login records.
- systemConfiguration.logoutURL [String] Deprecated
-
The logout redirect URL when sending the user’s browser to the
/oauth2/logout
URI of the FusionAuth Front End. This value is only used when a logout URL is not defined in your Application.Removed in version 1.8.0
In version 1.8.0 and beyond, logoutURL is managed per
Tenant
. - systemConfiguration.maximumPasswordAge.days [Integer] Deprecated
-
The password maximum age in days. The number of days after which FusionAuth will require a user to change their password.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.maximumPasswordAge.enabled [Boolean] Deprecated
-
Indicates that the maximum password age is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.minimumPasswordAge.seconds [Integer] Deprecated
-
The password minimum age in seconds. When enabled FusionAuth will not allow a password to be changed until it reaches this minimum age.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.minimumPasswordAge.enabled [Boolean] Deprecated
-
Indicates that the minimum password age is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password age settings are managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.encryptionScheme [String] Deprecated
-
The selected default encryption scheme.
Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.encryptionSchemeFactor [String] Deprecated
-
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.Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordEncryptionConfiguration.modifyEncryptionSchemeOnLogin [Boolean] Deprecated
-
When enabled a user’s hash configuration will be modified to match these configured settings.
Removed in version 1.8.0
In version 1.8.0 and beyond, password encryption configuration is managed per
Tenant
. - systemConfiguration.passwordValidationRules.maxLength [Integer] Deprecated
-
The maximum number of characters that are allowed for user passwords.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.minLength [Integer] Deprecated
-
The minimum number of characters that are required for user passwords.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.rememberPreviousPasswords.count [Integer] Deprecated
-
The number of previous passwords that should be remembered so they are not re-used by the User.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.rememberPreviousPasswords.enabled [Boolean] Deprecated
-
Indicates that the remember previous password validation is enabled and being enforced.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireMixedCase [Boolean] Deprecated
-
Indicates that passwords require an uppercase and lowercase character to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireNonAlpha [Boolean] Deprecated
-
Indicates that passwords require a non-alphanumeric character to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.passwordValidationRules.requireNumber [Boolean] Deprecated
-
Indicates that passwords require at least one number to be valid.
Removed in version 1.8.0
In version 1.8.0 and beyond, password validation rules are configured per
Tenant
. - systemConfiguration.reportTimezone [String]
-
The time zone used to adjust the stored UTC time when generating reports. Since reports are usually rolled up hourly, this timezone will be used for demarcating the hours.
For example:
America/Denver
orUS/Mountain
- systemConfiguration.uiConfiguration.headerColor [String]
-
A hexadecimal color to override the default menu color in the user interface.
- systemConfiguration.uiConfiguration.loginTheme.emailComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/complete page. This page is used after a user has verified their email address by clicking the URL in the email. After FusionAuth has updated their user object to indicate that their email was verified, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailSend [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/send page. This page is used after a user has asked for the verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.emailVerify [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /email/verify page by clicking the URL from the verification email and the
verificationId
has expired. FusionAuth expiresverificationId
after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.enabled [Boolean] Deprecated
-
Indicates that the login theme is enabled and will be used to style the login pages.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.helpers [String] Deprecated
-
A FreeMarker template that contains all of the macros and templates used by the rest of the
loginTheme
FreeMarker templates (i.e.oauth2Authorize
). This allows you to configure the general layout of your UI configuration and login theme without having to copy and paste HTML into each of the templates.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2Authorize [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/authorize page. This is the main login page for FusionAuth and is used for all interactive OAuth and OpenId Connect workflows.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2Error [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/error page. This page is used if the user starts or is in the middle of the OAuth workflow and any type of error occurs. This could be caused by the user messing with the URL or internally some type of information wasn’t passed between the OAuth endpoints correctly. For example, if you are federating login to an external IdP and that IdP does not properly echo the
state
parameter, FusionAuth’s OAuth workflow will break and this page will be displayed.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.oauth2TwoFactor [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /oauth2/two-factor page. This page is used if the user has two-factor authentication enabled and they need to type in their code again. FusionAuth will properly handle the SMS or authenticator app processing on the back end. This page contains the form that the user will put their code into.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordChange [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/change page. This page is used if the user is required to change their password or if they have requested a password reset. This page contains the form that allows the user to provide a new password.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/complete page. This page is used after the user has successfully updated their password (or reset it). This page should instruct the user that their password was updated and that they need to login again.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordForgot [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/forgot page. This page is used when a user starts the forgot password workflow. This page renders the form where the user types in their email address.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.passwordSent [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /password/sent page. This page is used when a user has submitted the forgot password form with their email. FusionAuth does not indicate back to the user if their email address was valid in order to prevent malicious activity that could reveal valid email addresses. Therefore, this page should indicate to the user that if their email was valid, they will receive an email shortly with a link to reset their password.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationComplete [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/complete page. This page is used after a user has verified their email address for a specific application (i.e. a user registration) by clicking the URL in the email. After FusionAuth has updated their registration object to indicate that their email was verified, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationSend [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/send page. This page is used after a user has asked for the application specific verification email to be resent. This can happen if the URL in the email expired and the user clicked it. In this case, the user can provide their email address again and FusionAuth will resend the email. After the user submits their email and FusionAuth re-sends a verification email to them, the browser is redirected to this page.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.registrationVerify [String] Deprecated
-
A FreeMarker template that is rendered when the user requests the /registration/verify page by clicking the URL from the application specific verification email and the
verificationId
has expired. FusionAuth expiresverificationId
after a period of time (which is configurable). If the user has a URL from the verification email that has expired, this page will be rendered and the error will be displayed to the user.Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.loginTheme.stylesheet [String] Deprecated
-
A CSS stylesheet used to style the login page and other templates such as forgot password, and verify email.
Removed in version 1.8.0
In version 1.8.0 and beyond, theme configuration is managed per
Tenant
and themes are configured using theTheme
API or via the UI. - systemConfiguration.uiConfiguration.logoURL [String]
-
A URL of a logo to override the default FusionAuth logo in the user interface.
- systemConfiguration.uiConfiguration.menuFontColor [String]
-
A hexadecimal color to override the default menu font color in the user interface.
{
"systemConfiguration": {
"auditLogConfiguration": {
"delete": {
"enabled": true,
"numberOfDaysToRetain": 90
}
},
"corsConfiguration": {
"allowCredentials": true,
"allowedHeaders": [
"Accept",
"Access-Control-Request-Headers",
"Access-Control-Request-Method",
"Authorization",
"Content-Type",
"Last-Modified",
"Origin",
"X-FusionAuth-TenantId",
"X-Requested-With"
],
"allowedMethods": [
"GET",
"POST",
"HEAD",
"OPTIONS",
"PUT",
"DELETE"
],
"allowedOrigins": [
"*"
],
"debug": false,
"enabled": true,
"exposedHeaders": [
"Access-Control-Allow-Origin",
"Access-Control-Allow-Credentials"
],
"preflightMaxAgeInSeconds": 1800
},
"eventLogConfiguration": {
"numberToRetain": 10000
},
"loginRecordConfiguration": {
"delete": {
"enabled": true,
"numberOfDaysToRetain": 90
}
},
"reportTimezone": "America/Denver",
"uiConfiguration": {
"headerColor": "303030",
"logoURL": "https://local.fusionauth.io/images/logo.svg",
"menuFontColor": "F0F0F0"
}
}
}
Export System Logs
Available Since Version 1.16.0
This API is used to export the System Logs, the response will be a compressed zip archive containing the logs from the configured log directory. When running FusionAuth on Docker or other container service where logs are written to stdout
and not written to the file system, this API will return an empty archive.
Request
GET /api/system/log/export?dateTimeSecondsFormat={dateTimeSecondsFormat}&lastNBytes={lastNBytes}&zoneId={zoneId}
When calling the API using a GET
request you will send the export criteria on the URL using request parameters.
Request Parameters
- dateTimeSecondsFormat [String] Optional defaults to [see description]
-
The format string used to format the date and time columns in the export result.
When this parameter is omitted a default format of
M/d/yyyy hh:mm:ss a z
will be used. See the DateTimeFormatter patterns for additional examples. - lastNBytes [Long] Optional defaults to
65,536
-
The number of bytes to retrieve from the end of each of the system logs. When this value is
-1
, the entire log will be downloaded. - zoneId [String] Optional defaults to [see description]
-
The time zone used to calculate the current time and build the filename.
For example:
America/Denver
orUS/Mountain
When this parameter is omitted the configured default report time zone will be used. See reportTimezone in the System Configuration API.
POST /api/system/system-log/export
When calling the API using a POST
request you will send the export criteria in a JSON request body.
Request Body
- dateTimeSecondsFormat [String] Optional defaults to [see description]
-
The format string used to format the date and time columns in the export result.
When this parameter is omitted a default format of
M/d/yyyy hh:mm:ss a z
will be used. See the DateTimeFormatter patterns for additional examples. - lastNBytes [Long] Optional defaults to
65,536
-
The number of bytes to retrieve from the end of each of the system logs. When this value is
-1
, the entire log will be downloaded. - zoneId [String] Optional defaults to [see description]
-
The time zone used to adjust the stored UTC time in the export result.
For example:
America/Denver
orUS/Mountain
When this parameter is omitted the configured default report time zone will be used. See reportTimezone in the System Configuration API.
{
"dateTimeSecondsFormat": "M/d/yyyy hh:mm:ss a z",
"zoneId": "America/Denver",
"lastNBytes": -1
}
Response
The response for this API will contain a compressed zip of the system logs.
Code | Description |
---|---|
200 |
The request was successful. The response will be a compressed archive byte stream with a |
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. |
Retrieve the Logging Level
The Logger API is used to retrieve the current log level for a particular logger by name.
This API is subject to change and should only be used under instruction from FusionAuth support.
Request
Retrieve the logging level by logger name
GET /api/logger?name={name}
Request Parameters
- name [String] Required
-
The logger name for which you are requesting to retrieve the current logging level.
Response
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
- name [String]
-
The name of the logger.
- level [String]
-
The current logging level. Possible values are:
-
error
-
warn
-
info
-
debug
-
trace
-
off
-
{
"level": "info"
}
Update the Logging Level
This API is used to update the log level for a particular FusionAuth package.
This API is subject to change and should only be used under instruction from FusionAuth support.
Request
Update the logging level by logger name
POST /api/logger
Request Headers
- Content-Type [String] Required
-
The request body is expected to be sent using form encoded data. Ensure your HTTP client sends the
Content-Type
request header set toapplication/x-www-form-urlencoded
.
Request Parameters
- name [String] Required
-
The logger name for which you are requesting to update the current logging level.
- level [String] Required
-
The requested logging level. Possible values are:
-
error
-
warn
-
info
-
debug
-
trace
-
off
-
Response
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
- level [String]
-
The logging level. If the request was successful, this value should be equal to the request value. Possible values are:
-
error
-
warn
-
info
-
debug
-
trace
-
off
-
{
"level": "info"
}
Rebuild the Elasticsearch index
Available Since Version 1.28.0
This API is used to rebuild the Elasticsearch index. In general you do not need to rebuild the search index at runtime, and doing will cause additional CPU and I/O overhead to FusionAuth until the request has completed. Please be careful with this API.
This API may be useful if you are building a new FusionAuth environment from an existing database w/out moving over an existing search index. In this scenario you will need to rebuild the search index from the database in order see the Users show up in the UI or use any of the Search APIs.
Request
Rebuild the Elasticsearch index
POST /api/system/reindex
Request Body
- index [String] Required
-
The name of the index to rebuild. The possible values are:
-
fusionauth_entity
The entity search index -
fusionauth_user
The user search index
-
{
"index": "fusionauth_user"
}
Response
Code | Description |
---|---|
202 |
The request was successful. The re-index request has been started. No response body will be returned. |
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. |
Retrieve the status of an index rebuild
Available Since Version 1.28.0
This API is used to retrieve the status of a reindex request. This may be useful to identify if an existing re-index operation has been completed.
Request
Retrieve the status the Elasticsearch reindex operation
GET /api/system/reindex
Response
Code | Description |
---|---|
202 |
A re-index operation is currently in progress. |
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 |
A re-index operation is not currently in progress. No response body will be returned. |
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. |
Retrieve System Status
The Status API is used to retrieve the current status and metrics for FusionAuth. This is useful for health checks and monitoring.
FusionAuth also supports a system status check using Prometheus.
Request
Return the system status without an API key
GET /api/status
Return the system status with an API key
GET /api/status
Response
The JSON response from the Status API is complex and subject to change. The only exception is the version
key.
version
will not change and will be returned as below. As a reminder, an API key is required to obtain this value.
{
//..
"version": "1.26.1"
//..
}
The specific contents of the JSON body are not documented here. If you choose to use this API for monitoring purposes you should primarily use the response code to indicate server health. If you receive a 200
you may consider FusionAuth in a healthy state. The response body is intended for use by FusionAuth support.
Code | Description |
---|---|
200 |
The FusionAuth is functioning properly |
452 |
The FusionAuth is failing to make a JDBC connection to the configured database. Available since 1.19.0 |
453 |
The FusionAuth database connection pool connectivity is below the healthy threshold. Additional information may be available in the JSON response which is retrieved when using an API key. Available since 1.19.0 |
454 |
The FusionAuth database connectivity pool connectivity is below the healthy threshold. Additional information may be available in the JSON response which is retrieved when using an API key. Available since 1.19.0 |
460 |
FusionAuth is using Elasticsearch and the search service is reporting an unhealthy cluster status. In a cluster with 2+ nodes, this means the cluster status is being reported as Available since 1.19.0 |
500 |
The FusionAuth server is not functioning properly. This could indicate that the database connectivity failed or one or more services within FusionAuth failed. Consult the FusionAuth Troubleshooting to learn more about the failure or contact FusionAuth support for assistance. |
Retrieve System Version
Available Since Version 1.27.0
The Version API is used to retrieve the current version of FusionAuth.
Request
Return the FusionAuth system version with an API key
GET /api/system/version
Response
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. |
Response Body
- version [String]
-
The version of the running FusionAuth instance.
{
"version": "1.27.0"
}
Retrieve System Metrics Using Prometheus
This API has been available since 1.26.0
This page contains the API that is used for retrieving FusionAuth application metrics to be used with Prometheus. Please refer to the Prometheus setup guide to understand how to set up Prometheus with the FusionAuth metrics endpoint.
Retrieve FusionAuth application metrics to use with Prometheus.
GET /api/prometheus/metrics
Request Parameters
There are no request parameters required with this API.
Response
The response to this API call contains currently available metrics. The metrics in this response are subject to change.
The following types of gauges are currently available.
-
JVM Buffers - A set of gauges for the count, usage, and capacity of the JVM’s direct and mapped buffer pools.
-
JVM class loading - A set of gauges for JVM classloader usage.
-
JVM garbage collection - A set of gauges for the counts and elapsed times of garbage collections.
-
JVM memory - A set of gauges for JVM memory usage, including stats on heap vs non-heap memory.
-
JVM threads - A set of gauges for the number of threads in their various states and deadlock detection.
-
Other JVM attributes - A Gauge implementation which queries an MBeanServerConnection for an attribute of an object.
# HELP jvm_memory_heap_committed Generated from Dropwizard metric import (metric=jvm.memory.heap.committed, type=com.codahale.metrics.jvm.MemoryUsageGaugeSet$8)
# TYPE jvm_memory_heap_committed gauge
jvm_memory_heap_committed 5.36870912E8
# HELP jvm_memory_non_heap_used Generated from Dropwizard metric import (metric=jvm.memory.non-heap.used, type=com.codahale.metrics.jvm.MemoryUsageGaugeSet$11)
# TYPE jvm_memory_non_heap_used gauge
jvm_memory_non_heap_used 1.66423384E8
# HELP jvm_memory_pools_CodeHeap__non_profiled_nmethods__used Generated from Dropwizard metric import (metric=jvm.memory.pools.CodeHeap-'non-profiled-nmethods'.used, type=com.codahale.metrics.jvm.MemoryUsageGaugeSet$17)
# TYPE jvm_memory_pools_CodeHeap__non_profiled_nmethods__used gauge
jvm_memory_pools_CodeHeap__non_profiled_nmethods__used 3.0334336E7
# HELP prime_mvc___admin_group_index__requests Generated from Dropwizard metric import (metric=prime-mvc.[/admin/group/index].requests, type=com.codahale.metrics.Timer)
# TYPE prime_mvc___admin_group_index__requests summary
prime_mvc___admin_group_index__requests{quantile="0.5",} 0.0
prime_mvc___admin_group_index__requests{quantile="0.75",} 0.0
prime_mvc___admin_group_index__requests{quantile="0.95",} 0.0
prime_mvc___admin_group_index__requests{quantile="0.98",} 0.0
prime_mvc___admin_group_index__requests{quantile="0.99",} 0.0
prime_mvc___admin_group_index__requests{quantile="0.999",} 0.0
prime_mvc___admin_group_index__requests_count 1.0
Feedback
How helpful was this page?
See a problem?
File an issue in our docs repo
Have a question or comment to share?
Visit the FusionAuth community forum.