Configuration REST API - v2

NEW IN RELEASE 138

The Configuration REST API - v2 allows users with the System Administrator role or the Edit System Configuration and Users permission, to configure the IQ Server.

Methods supported:

  1. GET
  2. PUT
  3. DELETE

Configuration properties supported:

Table below shows the IQ Server properties that can be configured using the Configuration REST API. "Supported From" column indicates the IQ server release that supports the configurability of each property using this REST API. 

IQ server installations running on older releases cannot be configured using this REST API. An upgrade will be required, which will migrate the properties from the existing config.yml file to the database and enable their configuration via this REST API.

PropertyDefault ValueDescriptionSupported From
baseUrlnullBase URL of the IQ Server for user-facing links back to the server.  Required for Email, SCM, and Jira integrations.Release 138
forceBaseUrlfalseDefault false value is desired. If true, force IQ Server to treat all inbound requests as originating from the configured baseURL instead of relying on inbound HTTP request headers to determine this dynamically.

Setting this to true in order for HTTP requests to the server to work correctly suggests a misconfiguration of an upstream server that is reverse proxying requests to IQ Server. The upstream server should instead be sending properly formatted Forwarded headers .
Release 138
frameAncestorsAllowlistnull

List of domains or parent URLs, passed as json. This property is used to add HTTP Content-Security-Policy (CSP) frame-ancestors directive to allow you to specify the domains or parent URLs that can frame the current resource, to prevent clickjacking. 'self' is always appended to this list.

Null value (default) indicates there is no restriction on the allowed domain or parent URLs. All domains can frame the resource.

Release 142
eventBus.maxThreadPoolSize500

The maximum number of threads that can be used for the EventBus.

The EventBus is used to asynchronously post various events (e.g. policy evaluation, entity management, license/security vulnerability overrides, etc). These events can then be consumed by various services (e.g. webhooks, source control, etc).

Release 142
csrfProtectiontrueEnables/disables cross-site request forgery protection. Defaults to true for increased security.Release 142

userAgentSuffix

nullA custom fragment to add to the "user-agent" for HTTP calls.Release 142
maxAdvancedSearchClauseCount2048The clause count limit for Advanced Search queries.Release 142
advancedSearchCSVExportDelimiter,The delimiter for the Advanced Search CSV export. The default is a comma.Release 142
policyMonitoringHour0Hour of the day (0-23) to schedule Policy Monitoring execution. The default is midnight.Release 142
webhookSecretPassphrase^d1swM!FF&qQPassphrase used to encrypt the Webhook Secret Keys.Release 142
*hdsUrlhttps://clm.sonatype.com/Sonatype Data Services URL.Release 142
sessionTimeout30

Session timeout value in minutes for IQ Server. This is a configurable value, with a default set as 30 minutes. Users will receive browser notifications (if enabled for Sonatype sites) when the session is about to expire.

Release 143
purgeScanFilesnullSupported value is withReports. If set to withReports, scan files will be deleted along with associated report files during Data Retention. Release 152
automaticQuarantineReleaseTimeIntervalInMinutes60Scheduling interval (in minutes) for Automatic Quarantine Release. Minimum value supported is 30 minutes.Release 152
quarantinedComponentReportExpirationTimeInHours12Expiration time for quarantine reportsRelease 161
waivedComponentUpgradeMonitoringEnabledfalseEnable or disable Waived component upgrade configurationRelease162
quarantinedItemCustomMessagenullCustom quarantined message of up to 500 chars to be displayed when a component fails a Firewall policy.
This feature requires Nexus Repository version 3.58 or newer.
Release 165
alpObservedLicenseDetectionEnabled

false

(true, for new installations of Lifecycle)

Enables observed license detection for additional ecosystems for users of Lifecycle with Advanced Legal Pack (ALP) add-on.Release 165

*Note: The property hdsUrl defaults to the value set in config.yml, if no value is found in the database.

GET Configuration Properties

To get one or more configuration properties you can make a GET request to the following path:

GET /api/v2/config?property={propertyName1}&property={propertyName2}

One or more values are required for the query parameter property . The values must match (case-sensitive) the names of the configuration properties you want to retrieve.

Example:

curl -u admin:admin123 'http://localhost:8070/api/v2/config?property=baseUrl&property=forceBaseUrl'

Response:

JSON response with HTTP status code 200 is returned with all the requested properties and their values.

If an invalid property name is supplied, then the request yields a bad request response with HTTP status code 400.

PUT Configuration Properties

To set one or more configuration properties you can make a PUT request to the following path:

PUT /api/v2/config

The request requires a JSON body as payload, which must include one or more of the properties described above.

Example:

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"baseUrl": "http://127.0.0.1:8070", "forceBaseUrl":true, "quarantinedItemCustomMessage":"My custom quarantine message."}' http://localhost:8070/api/v2/config

Example request using property frameAncestorsAllowlist passing list of domains as JSON. 

curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"frameAncestorsAllowlist": ["*first.com","second.*"]}' http://localhost:8070/api/v2/config

Response:

A successful request yields HTTP status code 204.

If an invalid property name or value is supplied, then the request yields a bad request response with HTTP status code 400.

DELETE Configuration Properties

To delete one or more configuration properties you can make a DELETE request to the following path:

DELETE /api/v2/config?property={propertyName1}&property={propertyName2}

One or more values are required for the query parameter property . The values must match (case-sensitive) the names of the configuration properties you want to retrieve.

Example:

curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/config?property=baseUrl&property=forceBaseUrl'

Response:

A successful request yields HTTP status code 204.

If an invalid property name is supplied, then the request yields a bad request response with HTTP status code 400.

Other related REST APIs: