Update the System Configuration

This API is used to update an existing System Configuration.

You must specify the Id of the System Configuration you are updating on the URI. 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

OpenAPI Spec

PATCH/api/system-configuration

OpenAPI Spec

For backward compatibility, the PATCH method accepts the same media type (specified by a Content-Type of application/json) and body as the PUT request. You can also use the following media types for different behavior:

JSON Patch/RFC 6902: application/json-patch+json
JSON Merge Patch/RFC 7396: merge-patch+json

For details, see the PATCH documentation.

Using a media type of application/json merges the provided request parameters into the existing object. As a result, all parameters are optional with PATCH: only provide the values you want to change. To remove a value, provide a null value. Patching an Array appends all values in the new list to the old list.

Request Body#

systemConfiguration.auditLogConfiguration.delete.enabledBooleanoptionalDefaults to false

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 to false audit logs will be preserved forever.

systemConfiguration.auditLogConfiguration.delete.numberOfDaysToRetainIntegeroptionalDefaults to 365

The number of days to retain the Audit Log. Required when auditLogConfiguration.delete.enabled is set to true.

Prior to version 1.30.0, this value was required when delete.enabled was equal to true.

systemConfiguration.corsConfiguration.allowCredentialsBooleanoptionalDefaults to false

The Access-Control-Allow-Credentials response header values as described by MDN Access-Control-Allow-Credentials.

systemConfiguration.corsConfiguration.allowedHeadersArray<String>optional

The Access-Control-Allow-Headers response header values as described by MDN Access-Control-Allow-Headers.

systemConfiguration.corsConfiguration.allowedMethodsArray<String>optional

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
PATCH

systemConfiguration.corsConfiguration.allowedOriginsArray<String>optional

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.debugBooleanoptionalDefaults to false

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.enabledBooleanoptionalDefaults to false

Whether the FusionAuth CORS filter will process requests made to FusionAuth.

systemConfiguration.corsConfiguration.exposedHeadersArray<String>optional

The Access-Control-Expose-Headers response header values as described by MDN Access-Control-Expose-Headers.

systemConfiguration.corsConfiguration.preflightMaxAgeInSecondsIntegeroptional

The Access-Control-Max-Age response header values as described by MDN Access-Control-Max-Age.

systemConfiguration.dataObjectoptional

An object that can hold any information about the System that should be persisted.

systemConfiguration.eventLogConfiguration.numberToRetainIntegeroptional

The number of events to retain. Once the number of event logs exceeds this configured value they will be deleted starting with the oldest event logs.

systemConfiguration.loginRecordConfiguration.delete.enabledBooleanoptionalDefaults to false

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 to false login records will be preserved forever.

systemConfiguration.loginRecordConfiguration.delete.numberOfDaysToRetainIntegeroptionalDefaults to 365

The number of days to retain login records. Required when loginRecordConfiguration.delete.enabled is set to true.

Prior to version 1.30.0, this value was required when delete.enabled was equal to true.

systemConfiguration.reportTimezoneStringrequired

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 or US/Mountain

systemConfiguration.trustedProxyConfiguration.trustPolicyStringDefaults to AllAvailable since 1.49.0

This setting is used to resolve the client IP address for use in logging, webhooks, and IP-based access control when an X-Forwarded-For header is provided. Because proxies are free to rewrite the X-Forwarded-For header, an untrusted proxy could write a value that allowed it to bypass IP-based ACLs, or cause an incorrect IP address to be logged or sent to a webhook.

Valid values are:

All: Consider all proxies in an X-Forwarded-For header to be trusted, and use the first address in the X-Forwarded-For header as the resolved address. This is less secure, and is provided for backwards compatibility.
OnlyConfigured: Only trust proxies named in the systemConfiguration.trustedProxyConfiguration.trusted list. In this case, the first untrusted proxy found will be used as the client IP address.

systemConfiguration.trustedProxyConfiguration.trustedArray<String>Available since 1.49.0

An array of IP addresses, representing the set of trusted upstream proxies. This value will be accepted but ignored when systemConfiguration.trustedProxyConfiguration.trustPolicy is set to All.

Values may be specified as IPv4, or IPv6 format, and ranges of addresses are also accepted in CIDR notation.

systemConfiguration.uiConfiguration.headerColorStringoptional

A hexadecimal color to override the default menu color in the user interface.

Example: 000000 would set the menu color to black.

systemConfiguration.uiConfiguration.logoURLStringoptional

A URL of a logo to override the default FusionAuth logo in the user interface.

systemConfiguration.uiConfiguration.menuFontColorStringoptional

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.usageDataConfiguration.enabledBooleanAvailable since 1.55.0

Whether or not FusionAuth collects and sends usage data to improve the product.

systemConfiguration.webhookEventLogConfiguration.enabledBooleanoptionalDefaults to trueAvailable since 1.57.0

Whether or not FusionAuth should create Webhook Event Logs. When true FusionAuth will create an event log for each webhook event and an attempt log for each attempt at sending the event to a webhook.

systemConfiguration.webhookEventLogConfiguration.delete.enabledBooleanoptionalDefaults to trueAvailable since 1.53.0

Whether or not FusionAuth should delete Webhook Event Logs based upon this configuration. When true the webhookEventLogConfiguration.delete.numberOfDaysToRetain value will be used to identify webhook event logs that are eligible for deletion. When this value is set to false webhook event logs will be preserved forever.

Prior to version 1.57.0 this defaults to false.

systemConfiguration.webhookEventLogConfiguration.delete.numberOfDaysToRetainIntegeroptionalDefaults to 30Available since 1.53.0

The number of days to retain Webhook Event Logs. Required when webhookEventLogConfiguration.delete.enabled is set to true.

Example Request JSON

{
  "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",
    "trustedProxyConfiguration": {
      "trustPolicy": "OnlyConfigured",
      "trusted": [
        "123.123.123.123"
      ]
    },
    "uiConfiguration": {
      "headerColor": "303030",
      "logoURL": "https://local.fusionauth.io/images/logo.svg",
      "menuFontColor": "F0F0F0"
    },
    "webhookEventLogConfiguration": {
      "enabled": true,
      "delete": {
        "enabled": true,
        "numberOfDaysToRetain": 90
      }
    }
  }
}

Response#

The response for this API contains the System Configuration.

Response Codes

Code	Description
200	The request was successful. The response will contain a JSON body.
400	The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present.
401	You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication.
500	There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503	The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body.

Response Body#

systemConfiguration.auditLogConfiguration.delete.enabledBoolean

systemConfiguration.auditLogConfiguration.delete.numberOfDaysToRetainInteger

The number of days to retain the Audit Log.

systemConfiguration.corsConfiguration.allowCredentialsBoolean

The Access-Control-Allow-Credentials response header values as described by MDN Access-Control-Allow-Credentials.

systemConfiguration.corsConfiguration.allowedHeadersArray<String>

The Access-Control-Allow-Headers response header values as described by MDN Access-Control-Allow-Headers.

systemConfiguration.corsConfiguration.allowedMethodsArray<String>

The Access-Control-Allow-Methods response header values as described by MDN Access-Control-Allow-Methods.

systemConfiguration.corsConfiguration.allowedOriginsArray<String>

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

systemConfiguration.corsConfiguration.enabledBoolean

Whether the FusionAuth CORS filter will process requests made to FusionAuth.

systemConfiguration.corsConfiguration.exposedHeadersArray<String>

The Access-Control-Expose-Headers response header values as described by MDN Access-Control-Expose-Headers.

systemConfiguration.corsConfiguration.preflightMaxAgeInSecondsInteger

The Access-Control-Max-Age response header values as described by MDN Access-Control-Max-Age.

systemConfiguration.dataObject

An object that can hold any information about the System that should be persisted.

systemConfiguration.eventLogConfiguration.numberToRetainInteger

The number of events to retain. Once the number of event logs exceeds this configured value they will be deleted starting with the oldest event logs.

systemConfiguration.loginRecordConfiguration.delete.enabledBoolean

systemConfiguration.loginRecordConfiguration.delete.numberOfDaysToRetainInteger

The number of days to retain login records.

systemConfiguration.reportTimezoneString

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 or US/Mountain

systemConfiguration.trustedProxyConfiguration.trustPolicyStringAvailable since 1.49.0

Valid values are:

All: Consider all proxies in an X-Forwarded-For header to be trusted, and use the first address in the X-Forwarded-For header as the resolved address. This is less secure, and is provided for backwards compatibility.
OnlyConfigured: Only trust proxies named in the systemConfiguration.trustedProxyConfiguration.trusted list. In this case, the first untrusted proxy found will be used as the client IP address.

systemConfiguration.trustedProxyConfiguration.trustedArray<String>Available since 1.49.0

An array of IP addresses, representing the set of trusted upstream proxies.

systemConfiguration.uiConfiguration.headerColorString

A hexadecimal color to override the default menu color in the user interface.

systemConfiguration.uiConfiguration.logoURLString

A URL of a logo to override the default FusionAuth logo in the user interface.

systemConfiguration.uiConfiguration.menuFontColorString

A hexadecimal color to override the default menu font color in the user interface.

systemConfiguration.usageDataConfiguration.enabledBooleanAvailable since 1.55.0

Whether or not FusionAuth collects and sends usage data to improve the product.

systemConfiguration.webhookEventLogConfiguration.enabledBooleanAvailable since 1.57.0

systemConfiguration.webhookEventLogConfiguration.delete.enabledBooleanAvailable since 1.53.0

Whether or not FusionAuth should delete Webhook Event Logs based upon this configuration. When true the webhookEventLogConfiguration.delete.numberOfDaysToRetain will be used to identify webhook event logs that are eligible for deletion. When this value is set to false webhook event logs will be preserved forever.

systemConfiguration.webhookEventLogConfiguration.delete.numberOfDaysToRetainIntegerAvailable since 1.53.0

The number of days to retain Webhook Event Logs.

Example Response JSON

{
  "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",
    "trustedProxyConfiguration": {
      "trustPolicy": "OnlyConfigured",
      "trusted": [
        "123.123.123.123"
      ]
    },
    "uiConfiguration": {
      "headerColor": "303030",
      "logoURL": "https://local.fusionauth.io/images/logo.svg",
      "menuFontColor": "F0F0F0"
    },
    "webhookEventLogConfiguration": {
      "enabled": true,
      "delete": {
        "enabled": true,
        "numberOfDaysToRetain": 90
      }
    }
  }
}