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:
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.
| Property | Default Value | Description | Supported From |
|---|---|---|---|
| baseUrl | null | Base URL of the IQ Server for user-facing links back to the server. Required for Email, SCM, and Jira integrations. | Release 138 |
| forceBaseUrl | false | Default 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 |
| frameAncestorsAllowlist | null | 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.maxThreadPoolSize | 500 | 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 |
| csrfProtection | true | Enables/disables cross-site request forgery protection. Defaults to true for increased security. | Release 142 |
userAgentSuffix | null | A custom fragment to add to the "user-agent" for HTTP calls. | Release 142 |
| maxAdvancedSearchClauseCount | 2048 | The 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 |
| policyMonitoringHour | 0 | Hour of the day (0-23) to schedule Policy Monitoring execution. The default is midnight. | Release 142 |
| webhookSecretPassphrase | ^d1swM!FF&qQ | Passphrase used to encrypt the Webhook Secret Keys. | Release 142 |
| *hdsUrl | https://clm.sonatype.com/ | Sonatype Data Services URL. | Release 142 |
| sessionTimeout | 30 | 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 |
| purgeScanFiles | null | Supported value is withReports. If set to withReports, scan files will be deleted along with associated report files during Data Retention. | Release 152 |
| automaticQuarantineReleaseTimeIntervalInMinutes | 60 | Scheduling interval (in minutes) for Automatic Quarantine Release. Minimum value supported is 30 minutes. | Release 152 |
| quarantinedComponentReportExpirationTimeInHours | 12 | Expiration time for quarantine reports | Release 161 |
| waivedComponentUpgradeMonitoringEnabled | false | Enable or disable Waived component upgrade configuration | Release162 |
| quarantinedItemCustomMessage | null | Custom 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/configExample 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/configResponse:
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.