FusionAuth developer image
FusionAuth developer logo
  • Back to site
  • Expert Advice
  • Blog
  • Developers
  • Downloads
  • Account
  • Contact sales
Navigate to...
  • Welcome
  • Getting Started
    • Getting Started
    • 5-minute Setup Guide
      • Overview
      • Docker
      • Fast Path
      • Sandbox
    • Setup Wizard & First Login
    • Register a User and Login
    • Self-service Registration
    • Start and Stop FusionAuth
    • Core Concepts
      • Overview
      • Users
      • Roles
      • Groups
      • Registrations
      • Applications
      • Tenants
      • Identity Providers
      • Authentication/Authorization
      • Integration Points
    • Example Apps
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • PHP
      • Python
      • Ruby
    • Tutorials
  • Installation Guide
    • Overview
    • System Requirements
    • Server Layout
    • Cloud
    • Cluster
    • Docker
    • Fast Path
    • Kubernetes
      • Overview
      • Deployment Guide
      • Minikube Setup
      • Amazon EKS Setup
      • Google GKE Setup
      • Microsoft AKS Setup
    • Kickstart™
    • Homebrew
    • Marketplaces
    • Packages
    • Database
    • FusionAuth App
    • FusionAuth Search
    • Common Configuration
  • Migration Guide
    • Overview
    • General
    • Auth0
    • Keycloak
    • Amazon Cognito
    • Firebase
    • Microsoft Azure AD B2C
    • Tutorial
  • Admin Guide
    • Overview
    • Account Portal
    • Config Management
    • Editions and Features
    • Key Rotation
    • Licensing
    • Monitoring
    • Prometheus Setup
    • Proxy Setup
    • Reference
      • Overview
      • Configuration
      • CORS
      • Data Types
      • Hosted Login Pages Cookies
      • Known Limitations
      • Password Hashes
    • Releases
    • Roadmap
    • Search And FusionAuth
    • Securing
    • Switch Search Engines
    • Technical Support
    • Troubleshooting
    • Upgrading
    • WebAuthn
  • Login Methods
    • Identity Providers
      • Overview
      • Apple
      • Epic Games
      • External JWT
        • Overview
        • Example
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
        • Overview
        • Amazon Cognito
        • Azure AD
        • Discord
        • Github
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • SAML v2
        • Overview
        • ADFS
        • Azure AD
      • SAML v2 IdP Initiated
        • Overview
        • Okta
      • Xbox
    • OIDC & OAuth 2.0
      • Overview
      • Endpoints
      • Tokens
      • OAuth Modes
    • Passwordless
      • Overview
      • Magic Links
      • WebAuthn & Passkeys
    • SAML v2 IdP
      • Overview
      • Google
      • Zendesk
  • Developer Guide
    • Overview
    • API Gateways
      • Overview
      • ngrok Cloud Edge
    • Client Libraries & SDKs
      • Overview
      • Dart
      • Go
      • Java
      • JavaScript
      • .NET Core
      • Node
      • OpenAPI
      • PHP
      • Python
      • React
      • Ruby
      • Typescript
    • Events & Webhooks
      • Overview
      • Writing a Webhook
      • Securing Webhooks
      • Events
        • Overview
        • Audit Log Create
        • Event Log Create
        • JWT Public Key Update
        • JWT Refresh
        • JWT Refresh Token Revoke
        • Kickstart Success
        • Group Create
        • Group Create Complete
        • Group Delete
        • Group Delete Complete
        • Group Update
        • Group Update Complete
        • Group Member Add
        • Group Member Add Complete
        • Group Member Remove
        • Group Member Remove Complete
        • Group Member Update
        • Group Member Update Complete
        • User Action
        • User Bulk Create
        • User Create
        • User Create Complete
        • User Deactivate
        • User Delete
        • User Delete Complete
        • User Email Update
        • User Email Verified
        • User IdP Link
        • User IdP Unlink
        • User Login Failed
        • User Login Id Dup. Create
        • User Login Id Dup. Update
        • User Login New Device
        • User Login Success
        • User Login Suspicious
        • User Password Breach
        • User Password Reset Send
        • User Password Reset Start
        • User Password Reset Success
        • User Password Update
        • User Reactivate
        • User Reg. Create
        • User Reg. Create Complete
        • User Reg. Delete
        • User Reg. Delete Complete
        • User Registration Update
        • User Reg. Update Complete
        • User Reg. Verified
        • User 2FA Method Add
        • User 2FA Method Remove
        • User Update
        • User Update Complete
    • Guides
      • Overview
      • Authentication Tokens
      • Exposing A Local Instance
      • JSON Web Tokens
      • Key Master
      • Localization and Internationalization
      • Multi-Factor Authentication
      • Multi-Tenant
      • Passwordless
      • Registration-based Email Verification
      • Searching With Elasticsearch
      • Securing Your APIs
      • Silent Mode
      • Single Sign-on
      • Two Factor (pre 1.26)
    • Integrations
      • Overview
      • CleanSpeak
      • Kafka
      • Twilio
    • Plugins
      • Overview
      • Writing a Plugin
      • Custom Password Hashing
    • User Control & Gating
      • Overview
      • Gate Unverified Users
      • Gate Unverified Registrations
      • User Account Lockout
  • Customization
    • Email & Templates
      • Overview
      • Configure Email
      • Email Templates
      • Email Variables
      • Message Templates
    • Lambdas
      • Overview
      • Apple Reconcile
      • Client Cred. JWT Populate
      • Epic Games Reconcile
      • External JWT Reconcile
      • Facebook Reconcile
      • Google Reconcile
      • HYPR Reconcile
      • JWT Populate
      • LDAP Connector Reconcile
      • LinkedIn Reconcile
      • Nintendo Reconcile
      • OpenID Connect Reconcile
      • SAML v2 Populate
      • SAML v2 Reconcile
      • SCIM Group Req. Converter
      • SCIM Group Resp. Convtr.
      • SCIM User Req. Converter
      • SCIM User Resp. Converter
      • Sony PSN Reconcile
      • Steam Reconcile
      • Twitch Reconcile
      • Twitter Reconcile
      • Xbox Reconcile
    • Messengers
      • Overview
      • Generic Messenger
      • Twilio Messenger
    • Themes
      • Overview
      • Examples
      • Helpers
      • Localization
      • Template Variables
  • Premium Features
    • Overview
    • Advanced Registration Forms
    • Advanced Threat Detection
    • Application Specific Themes
    • Breached Password Detection
    • Connectors
      • Overview
      • Generic Connector
      • LDAP Connector
      • FusionAuth Connector
    • Entity Management
    • SCIM
      • Overview
      • Azure AD Client
      • Okta Client
      • SCIM-SDK
    • Self Service Account Mgmt
      • Overview
      • Updating User Data & Password
      • Add Two-Factor Authenticator
      • Add Two-Factor Email
      • Add Two-Factor SMS
      • Add WebAuthn Passkey
      • Customizing
      • Troubleshooting
    • WebAuthn
  • APIs
    • Overview
    • Authentication
    • Errors
    • API Explorer
    • Actioning Users
    • API Keys
    • Applications
    • Audit Logs
    • Connectors
      • Overview
      • Generic
      • LDAP
    • Consents
    • Emails
    • Entity Management
      • Overview
      • Entities
      • Entity Types
      • Grants
    • Event Logs
    • Families
    • Forms
    • Form Fields
    • Groups
    • Identity Providers
      • Overview
      • Links
      • Apple
      • External JWT
      • Epic Games
      • Facebook
      • Google
      • HYPR
      • LinkedIn
      • Nintendo
      • OpenID Connect
      • SAML v2
      • SAML v2 IdP Initiated
      • Sony PlayStation Network
      • Steam
      • Twitch
      • Twitter
      • Xbox
    • Integrations
    • IP Access Control Lists
    • JWT
    • Keys
    • Lambdas
    • Login
    • Message Templates
    • Messengers
      • Overview
      • Generic
      • Twilio
    • Multi-Factor/Two Factor
    • Passwordless
    • Reactor
    • Registrations
    • Reports
    • SCIM
      • Overview
      • SCIM User
      • SCIM Group
      • SCIM EnterpriseUser
      • SCIM Service Provider Config.
    • System
    • Tenants
    • Themes
    • Users
    • User Actions
    • User Action Reasons
    • User Comments
    • WebAuthn
    • Webhooks
  • Release Notes

    System APIs

    Overview

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

    Documentation for this API has been updated for version 1.30 and above. For previous versions, you can view the Pre 1.30 System documentation if needed.

    System Configuration

    • Retrieve the System Configuration

    • Update the System Configuration

    System Tools

    • Export System Logs

    • Retrieve the Logging Level

    • Update the Logging Level

    • Rebuild the Elasticsearch index

    • Retrieve the status of an index rebuild

    System Status

    • Retrieve System Status

    • Retrieve System Version

    • Retrieve System Metrics Using Prometheus

    Retrieve the System Configuration

    This API is used to retrieve the System Configuration.

    Request

    Retrieve the System Configuration

    URI

    GET /api/system-configuration

    Response

    The response for this API contains the System Configuration.

    Table 1. 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.enabled [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 [Integer]

    The number of days to retain the Audit Log.

    systemConfiguration.corsConfiguration.allowCredentials [Boolean]

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

    systemConfiguration.corsConfiguration.allowedHeaders [Array<String>]

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

    systemConfiguration.corsConfiguration.allowedMethods [Array<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

    systemConfiguration.corsConfiguration.allowedOrigins [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 [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 [Boolean]

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

    systemConfiguration.corsConfiguration.exposedHeaders [Array<String>]

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

    systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds [Integer]

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

    systemConfiguration.data [Object]

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

    systemConfiguration.eventLogConfiguration.numberToRetain [Integer]

    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.loginRecordConfiguration.delete.enabled [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 [Integer]

    The number of days to retain login records.

    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 or US/Mountain
    systemConfiguration.uiConfiguration.headerColor [String]

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

    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.

    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",
        "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

    URI

    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 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.enabled [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 [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 [Boolean] Optional defaults to false

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

    systemConfiguration.corsConfiguration.allowedHeaders [Array<String>] Optional

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

    systemConfiguration.corsConfiguration.allowedMethods [Array<String>] Optional

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

    systemConfiguration.corsConfiguration.allowedOrigins [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 [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 [Boolean] Optional defaults to false

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

    systemConfiguration.corsConfiguration.exposedHeaders [Array<String>] Optional

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

    systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds [Integer] Optional

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

    systemConfiguration.data [Object] Optional

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

    systemConfiguration.eventLogConfiguration.numberToRetain [Integer] Optional defaults to 10,000

    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.loginRecordConfiguration.delete.enabled [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 [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 [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.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.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.
    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",
        "uiConfiguration": {
          "headerColor": "303030",
          "logoURL": "https://local.fusionauth.io/images/logo.svg",
          "menuFontColor": "F0F0F0"
        }
      }
    }

    Response

    The response for this API contains the System Configuration.

    Table 2. 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.enabled [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 [Integer]

    The number of days to retain the Audit Log.

    systemConfiguration.corsConfiguration.allowCredentials [Boolean]

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

    systemConfiguration.corsConfiguration.allowedHeaders [Array<String>]

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

    systemConfiguration.corsConfiguration.allowedMethods [Array<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

    systemConfiguration.corsConfiguration.allowedOrigins [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 [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 [Boolean]

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

    systemConfiguration.corsConfiguration.exposedHeaders [Array<String>]

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

    systemConfiguration.corsConfiguration.preflightMaxAgeInSeconds [Integer]

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

    systemConfiguration.data [Object]

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

    systemConfiguration.eventLogConfiguration.numberToRetain [Integer]

    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.loginRecordConfiguration.delete.enabled [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 [Integer]

    The number of days to retain login records.

    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 or US/Mountain
    systemConfiguration.uiConfiguration.headerColor [String]

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

    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.

    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",
        "uiConfiguration": {
          "headerColor": "303030",
          "logoURL": "https://local.fusionauth.io/images/logo.svg",
          "menuFontColor": "F0F0F0"
        }
      }
    }

    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

    URI

    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

    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.

    includeArchived [Boolean] Optional defaults to false Available 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.

    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.

    This parameter is ignored when includeArchived is true .

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

    URI

    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

    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.

    includeArchived [Boolean] Optional defaults to false Available 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.

    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.

    This parameter is ignored when includeArchived is true .

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

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

    URI

    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

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

    name [String]

    The name of the logger.

    level [String]

    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

    URI

    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 to application/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

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

    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

    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.

    Request

    Rebuild the Elasticsearch index

    URI

    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

    Example Request JSON
    
    {
      "index": "fusionauth_user"
    }

    Response

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

    URI

    GET /api/system/reindex

    Response

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

    FusionAuth also supports a system status check using Prometheus.

    Request

    Return the system status without an API key

    URI

    GET /api/status

    Return the system status with an API key

    URI

    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.

    Table 8. Response Codes
    Code Description

    200

    The FusionAuth is functioning properly

    452

    The FusionAuth is failing to make a JDBC connection to the configured database.

    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.

    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.

    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.

    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

    The Version API is used to retrieve the current version of FusionAuth.

    Request

    Return the FusionAuth system version with an API key

    URI

    GET /api/system/version

    Response

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

    version [String]

    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.

    URI

    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

    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.

    © 2023 FusionAuth
    Subscribe for developer updates