Update the System Configuration API

Edit on GitHubView Markdown
On this page

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#

Global API Key Authentication
Update the System Configuration
PUT/api/system-configuration
OpenAPI Spec
PATCH/api/system-configuration
OpenAPI Spec
Note

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:

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.enabled
  • Type: Boolean
  • Optional
  • Defaults 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.numberOfDaysToRetain
  • Type: Integer
  • Optional
  • Defaults 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.allowCredentials
  • Type: Boolean
  • Optional
  • Defaults to false

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

systemConfiguration.corsConfiguration.allowedHeaders
  • Type: Array<String>
  • Optional

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

systemConfiguration.corsConfiguration.allowedMethods
  • Type: Array<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.allowedOrigins
  • Type: Array<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.debug
  • Type: Boolean
  • Optional
  • Defaults 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.enabled
  • Type: Boolean
  • Optional
  • Defaults to false

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

systemConfiguration.corsConfiguration.exposedHeaders
  • Type: Array<String>
  • Optional

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

systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds
  • Type: Integer
  • Optional

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

systemConfiguration.data
  • Type: Object
  • Optional

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

systemConfiguration.eventLogConfiguration.numberToRetain
  • Type: Integer
  • Optional

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.enabled
  • Type: Boolean
  • Optional
  • Defaults 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.numberOfDaysToRetain
  • Type: Integer
  • Optional
  • Defaults 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.reportTimezone
  • Type: 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 or US/Mountain

systemConfiguration.trustedProxyConfiguration.trustPolicy
  • Type: String
  • Defaults to All
  • Available 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.trusted
  • Type: Array<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.headerColor
  • Type: 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.logoURL
  • Type: String
  • Optional

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

systemConfiguration.uiConfiguration.menuFontColor
  • Type: 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.usageDataConfiguration.enabled
  • Type: Boolean
  • Available since 1.55.0

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

systemConfiguration.webhookEventLogConfiguration.enabled
  • Type: Boolean
  • Optional
  • Defaults to true
  • Available 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.enabled
  • Type: Boolean
  • Optional
  • Defaults to true
  • Available 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.numberOfDaysToRetain
  • Type: Integer
  • Optional
  • Defaults to 30
  • Available 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
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The 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
  • Type: Boolean

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.numberOfDaysToRetain
  • Type: Integer

The number of days to retain the Audit Log.

systemConfiguration.corsConfiguration.allowCredentials
  • Type: Boolean

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

systemConfiguration.corsConfiguration.allowedHeaders
  • Type: Array<String>

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

systemConfiguration.corsConfiguration.allowedMethods
  • Type: Array<String>

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

systemConfiguration.corsConfiguration.allowedOrigins
  • Type: Array<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.debug
  • Type: Boolean

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
  • Type: Boolean

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

systemConfiguration.corsConfiguration.exposedHeaders
  • Type: Array<String>

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

systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds
  • Type: Integer

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

systemConfiguration.data
  • Type: Object

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

systemConfiguration.eventLogConfiguration.numberToRetain
  • Type: Integer

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.enabled
  • Type: Boolean

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.numberOfDaysToRetain
  • Type: Integer

The number of days to retain login records.

systemConfiguration.reportTimezone
  • Type: 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 or US/Mountain

systemConfiguration.trustedProxyConfiguration.trustPolicy
  • Type: String
  • Available 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.trusted
  • Type: Array<String>
  • Available since 1.49.0

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

systemConfiguration.uiConfiguration.headerColor
  • Type: String

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

systemConfiguration.uiConfiguration.logoURL
  • Type: String

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

systemConfiguration.uiConfiguration.menuFontColor
  • Type: String

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

systemConfiguration.usageDataConfiguration.enabled
  • Type: Boolean
  • Available since 1.55.0

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

systemConfiguration.webhookEventLogConfiguration.enabled
  • Type: Boolean
  • Available 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.enabled
  • Type: Boolean
  • Available 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.numberOfDaysToRetain
  • Type: Integer
  • Available 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
      }
    }
  }
}

Related

APIs

System API

Learn about the APIs for retrieving and updating the system configuration.

fusionauth apirest apihttp api
APIs

Retrieve the System Configuration API

API documentation for the FusionAuth Retrieve the System Configuration API.

fusionauth apirest apihttp api
APIs

Export System Logs API

API documentation for the FusionAuth Export System Logs API.

fusionauth apirest apihttp api
APIs

Rebuild the Elasticsearch index API

API documentation for the FusionAuth Rebuild the Elasticsearch index API.

fusionauth apirest apihttp api