APIs

System

Overview

This page contains the APIs that are used for retrieving and updating the system configuration.

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.

Response Codes

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

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

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

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

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.

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.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": {
      "delete": {
        "enabled": true,
        "numberOfDaysToRetain": 90
      }
    }
  }
}

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

PATCH /api/system-configuration

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.

When using the PATCH method with a Content-Type of application/json the provided request parameters will be merged 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 an Array 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.enabledBooleanDefaults to false

systemConfiguration.auditLogConfiguration.delete.numberOfDaysToRetainIntegerDefaults 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.allowCredentialsBooleanDefaults to false

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. The possible values are:

GET
POST
PUT
DELETE
HEAD
OPTIONS
PATCH

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

systemConfiguration.corsConfiguration.enabledBooleanDefaults to false

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

systemConfiguration.loginRecordConfiguration.delete.numberOfDaysToRetainIntegerDefaults 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

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

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

Example: 000000 would set the menu color to black.

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.

Example: FFFFFF would set the menu font color to white.

systemConfiguration.webhookEventLogConfiguration.delete.enabledBooleanDefaults to falseAvailable since 1.53.0

systemConfiguration.webhookEventLogConfiguration.delete.numberOfDaysToRetainIntegerDefaults 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": {
      "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.webhookEventLogConfiguration.delete.enabledBooleanAvailable since 1.53.0

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": {
      "delete": {
        "enabled": true,
        "numberOfDaysToRetain": 90
      }
    }
  }
}

Export System Logs

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

Export the System Logs

GET /api/system/log/export?dateTimeSecondsFormat={dateTimeSecondsFormat}&includeArchived=true&zoneId={zoneId}

When calling the API using a GET request you will send the export criteria on the URL using request parameters.

Request Parameters

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

includeArchivedBooleanDefaults to falseAvailable since 1.43.0

Whether to include rotated, compressed logs in addition to the set of active logs in the export result. The default behavior is to only export the set of logs actively being written.

When this parameter is true, all available logs are exported. Additionally, if provided, the lastNBytes parameter is ignored.

lastNBytesLong

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.

This parameter is ignored when includeArchived is true .

zoneIdString

The time zone used to adjust the stored UTC time in the export result.

For example:

America/Denver or US/Mountain

When this parameter is omitted the configured default report time zone will be used. See reportTimezone in the System Configuration API.

Export the System Logs

POST /api/system/log/export

When calling the API using a POST request you will send the export criteria in a JSON request body.

Request Body

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

includeArchivedBooleanDefaults to falseAvailable since 1.43.0

Whether to include rotated, compressed logs in addition to the set of active logs in the export result. The default behavior is to only export the set of logs actively being written.

When this parameter is true, all available logs are exported. Additionally, if provided, the lastNBytes parameter is ignored.

lastNBytesLong

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.

This parameter is ignored when includeArchived is true .

zoneIdString

The time zone used to adjust the stored UTC time in the export result.

For example:

America/Denver or US/Mountain

When this parameter is omitted the configured default report time zone will be used. See reportTimezone in the System Configuration API.

Example Request JSON

{
  "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.

Response Codes

Code	Description
200	The request was successful. The response will be a compressed archive byte stream with a "Content-Type" of "application/zip".
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

nameStringrequired

The logger name for which you are requesting to retrieve the current logging level.

Response

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.

Response Body

nameString

The name of the logger.

levelString

The current logging level. Possible values are:

error
warn
info
debug
trace
off

Example JSON Response

{
  "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-TypeStringrequired

The request body is expected to be sent using form encoded data. Ensure your HTTP client sends the Content-Type request header set to application/x-www-form-urlencoded.

Request Parameters

nameStringrequired

The logger name for which you are requesting to update the current logging level.

levelStringrequired

The requested logging level. Possible values are:

error
warn
info
debug
trace
off

Response

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.

Response Body

levelString

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

Example JSON Response

{
  "level": "info"
}

Rebuild the Elasticsearch index

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.

Beginning in version 1.48.0, index aliases are used to minimize any disruption to API requests utilizing the search index. In practice this should not affect you, but please be aware that FusionAuth will use the configured index name as an alias, and the actual index name will be suffixed with _a or _b.

For example, the default name for the user index is fusionauth_user. You can expect to see the actual index to be created as fusionauth_user_a with an alias added named fusionauth_user. Using this same example, when a reindex request is started, a new index named fusionauth_user_b will be created, and when the re-index operation is complete the alias fusionauth_user will be changed to point to fusionauth_user_b and the fusionauth_user_a will be deleted.

Request

Rebuild the Elasticsearch index

POST /api/system/reindex

Request Body

indexStringrequired

The name of the index to rebuild. The possible values are:

fusionauth_entity The entity search index
fusionauth_user The user search index

Please note, that while the index names can be modified using the FusionAuth configuration, that does not change how you call this API. For example, even if you modify the configuration to name the user search index fusionauth_user_dev, you will still use fusionauth_user to indicate you wish to rebuild the user search index.

Example Request JSON

{
  "index": "fusionauth_user"
}

Response

Response Codes

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

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

Response Codes

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.

By default, this API requires authentication. If you prefer to allow unauthenticated access to this endpoint from local scrapers, you may set fusionauth-app.local-metrics.enabled=true. See the configuration reference for more info.

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.

The version key will not change and will be returned as below. As a reminder, an API key is required to obtain this value unless explicitly allowed from localhost.

{
  "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.

Response Codes

Code	Description
200	FusionAuth is functioning properly
452	FusionAuth is failing to make a JDBC connection to the configured database.
453	The FusionAuth database connection pool connectivity is below the healthy threshold. This means requests are waiting too long to obtain a connection to the database. Additional information may be available in the JSON response which is retrieved when using an API key.
454	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. As of version `1.51.1` this status code will no longer be returned based upon the connectivity health check. In practice you only need to monitor for `452` to ensure FusionAuth is able to connect to the database.
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 `yellow` or `red`. In a single-node Elasticsearch configuration this means the cluster status is `red.` As of version `1.51.1` this status code will no longer be returned based upon the Elasticsearch health check. If you are using an external Elasticsearch or OpenSearch service, you will want to monitor that separately from FusionAuth.
500	FusionAuth 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 Health

This API has been available since 1.51.1

The Health API is used to monitor the health of the FusionAuth service. This endpoint is specifically intended for use by a load balancer to understand when FusionAUth is available, live and ready for requests. Prefer this endpoint to the Status API when using it for a load balancer or a Kubernetes readiness check.

This API does not require an API key.

Request

Return the system health

GET /api/health

Response

This API does not return a JSON response body.

Response Codes

Code	Description
200	FusionAuth is functioning properly and can accept requests.
500	FusionAuth is not functioning properly. This will generally indicate that FusionAuth is not able to communicate with the database or complete I/O operations.

Retrieve System Version

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

Response Codes

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

versionString

The version of the running FusionAuth instance.

Example JSON Response

{
  "version": "1.27.0"
}

Retrieve System Metrics Using Prometheus

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.

Example Prometheus Response

  # 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

Results

Recent

System

Overview

Retrieve the System Configuration

Request

Response

Response Body

Update the System Configuration

Request

Request Body

Response

Response Body

Export System Logs

Request

Request Parameters

Request Body

Response

Retrieve the Logging Level

Request

Request Parameters

Response

Response Body

Update the Logging Level

Request

Request Headers

Request Parameters

Response

Response Body

Rebuild the Elasticsearch index

Request

Request Body

Response

Retrieve the status of an index rebuild

Request

Response

Retrieve System Status

Request

Response

Retrieve System Health

Request

Response

Retrieve System Version

Request

Response

Response Body

Retrieve System Metrics Using Prometheus

Request Parameters

Response

Results

Recent