Configuration REST API
The Configuration REST API allows users with the System Administrator role or the Edit System Configuration and Users permission, to configure the server.
API Requests
GET Configuration Properties
To get one or more configuration properties you can make a GET request to the config:
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.
curl -u admin:admin123 'http://localhost:8070/api/v2/config?property=baseUrl&property=forceBaseUrl'
A JSON response with the requested properties and values.
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.
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"baseUrl": "http://sonatype.com:8070", "forceBaseUrl":true, "quarantinedItemCustomMessage":"My custom quarantine message."}' http://localhost:8070/api/v2/configA successful request returns the HTTP status code 204. An invalid property name returns a 400 code.
DELETE Configuration Properties
To delete one or more configuration properties make a DELETE request to the config endpoint:
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.
curl -u admin:admin123 -X DELETE 'http://localhost:8070/api/v2/config?property=baseUrl&property=forceBaseUrl'
A successful request returns the HTTP status code 204. An invalid property name returns a 400 code.
IQ Server Connection Properties
Use the following properties to manage connecting to the IQ Server. The IQ Server supports the following solutions: Lifecycle, Developer, SBOM Manager, and Repository Firewall.
Base URL (required)
Setting the base URL (domain) of the IQ Server. This property is for user-facing links and is required for sending emails, following links in pull requests and CI servers, and connecting to reports in most integrations.
Property: baseUrl
Default: null
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"baseUrl": "https://example.sonatype.com/"}' https://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=baseUrl"User Session Timeout
Session timeout value in minutes for IQ Server. The user receives a browser notifications when the session is about to expire.
Property: sessionTimeout
Default: 30
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"sessionTimeout": 30}' https://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=sessionTimeout"Force the Base Url
When set to true, IQ Server treats inbound requests as originating from the baseURL instead of on inbound HTTP request headers to ignore a misconfigured upstream reverse proxy.
We recommend fixing the upstream server to send properly formatted forwarded headers instead of using this setting.
Property: forceBaseUrl
Default: false
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"forceBaseUrl": true}' https://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=forceBaseUrl"Frame Ancestors Allowlist
This property prevents clickjacking by adding an HTTP Content-Security-Policy (CSP) frame-ancestors directive to specify the domains or parent URLs that can frame the current resource. The property 'self' is appended to this list.
The default null value sets no restriction on the allowed domain or parent URLs. Any domain can frame the resource. Setting the property with a list of domains or parent URLs passed as JSON.
Property: frameAncestorsAllowlist
Default: null
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"frameAncestorsAllowlist": ["*first.com","second.*"]}' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=frameAncestorsAllowlist"Max Thread Pool Size
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 are consumed by various services (e.g. webhooks, source control, etc).
Property: eventBus.maxThreadPoolSize
Default: 500
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"eventBus.maxThreadPoolSize": 500}' https://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=eventBus.maxThreadPoolSize"User-Agent Suffix
The user-agent header is a header in a request for web access sent under the HTTP protocol. This header identifies the software program that was used to send the request. A custom fragment may be added to the end of the "user-agent" for HTTP calls. This fragment may be used with network firewalls in managing traffic from the IQ Server.
Property: userAgentSuffix
Default: null
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"userAgentSuffix ": "Approved" }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=userAgentSuffix"Enforce CSRF Protection
Enables/disables cross-site request forgery protection. The default is set to true to increase security.
Property: csrfProtection
Default: true
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"csrfProtection": true }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=csrfProtection"Sonatype Data Services URL
This property points to the Sonatype Data Services to receive up-to-date information. This value may be updated when a static remote IP is needed while configuring access through firewall rules. This value should not be changed unless directly by the Sonatype Support team.
Property: hdsUrl
Default: https://clm.sonatype.com/
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"hdsUrl": "https://clm.sonatype.com/" }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=hdsUrl"Allow Single-Sign On (SSO)
Use this property to redirect authentication to the SAML provider and skip the Sign-in dialog box.
Property: enableSsoOnly
Default: null
curl -u admin:admin123 -X POST -H "Content-Type: application/json" https://<iq-server-url>/api/v2/config/features/enableSsoOnly
To enable the IQ Sign-in dialog box again, use the DELETE method as show below.
curl -u admin:admin123 -X DELETE -H "Content-Type: application/json" https://<iq-server-url>/api/v2/config/features/enableSsoOnly
IQ Server Configuration Properties
Use the following properties to manage the IQ Server configuration. The IQ Server supports the following solutions: Lifecycle, Developer, SBOM Manager, and Repository Firewall.
Webhook Secret Key Passphrase (recommended)
This is the passphrase used to encrypt webhooks sent by IQ Server. Webhooks are used for notification integrations such as JIRA or with custom scripts. We recommend changing the default passphrase when using webhooks.
Property: webhookSecretPassphrase
Default: ^d1swM!FF&qQ
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"webhookSecretPassphrase": "S0natyp3_R0ckz!" }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=webhookSecretPassphrase"Enable Monitoring of Waived Components (recommended)
See Waived Component Upgrade Monitoring to learn more about this feature.
Property: waivedComponentUpgradeMonitoringEnabled
Default: false
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"waivedComponentUpgradeMonitoringEnabled": true }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=waivedComponentUpgradeMonitoringEnabled"Continuous Monitoring Start Time
Continuous Monitoring updates the report for applications not built regularly by performing an analysis from the most recent scan files. As each report may take a few minutes to run, this process should start in off-peak hours after the maintenance backup is made. The number represents the hour of the day with 0 starting at the system time of midnight. Note that the actual process begins on a random minute before or after the chosen hour to limit the load on Sonatype servers.
Property: policyMonitoringHour
Default: 0 ; hour of the day ranging from (0-23)
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"policyMonitoringHour": 2 }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=policyMonitoringHour"Access Allow List for REST APIs
List of usernames passed as JSON. This property is used to control the access to the public API.
When set, only the users specified in the list are allowed to make API calls. Set this property to null for unrestricted API access to authenticated users.
Property: apiAccessAllowList
Default: null
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"apiAccessAllowList": "[\"user1\",\"user2\"]" }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=apiAccessAllowList"Set the Maximum Search Causes
This parameter adjusts the limit for the number of clauses (query parameters) in the advanced search's Lucene query. Wildcard or open ended searches result in a large number of clauses that may have performance implications. The limit is in place to keep searches from overloading the server.
This parameter is relevant when non-admin users perform advanced searches across large numbers of organizations or applications. When the query generated contains too many clauses, an issue may occur. Adjusting the clause count controls the limit to avoid the error message.
The clause count limit for Advanced Search queries.
Property: maxAdvancedSearchClauseCount
Default: 2048
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"maxAdvancedSearchClauseCount": 5000 }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=maxAdvancedSearchClauseCount"Delimiter for Advanced Search CSV Export
The delimiter for the Advanced Search API when exporting to a CSV file.
Property: advancedSearchCSVExportDelimiter
Default: , (a comma)
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"advancedSearchCSVExportDelimiter":"," }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=advancedSearchCSVExportDelimiter"Enable Data Insights
Allows the IQ instance to send non-anonymized telemetry data to Sonatype. This data is used to generate Data Insights. Disabling this property will cause a degraded user experience.
Property: ADVANCED_REPORTING_INSIGHTS_ENABLED
Default: true
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"ADVANCED_REPORTING_INSIGHTS_ENABLED": true }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=ADVANCED_REPORTING_INSIGHTS_ENABLED"Restrict Success Metrics to a Specific Stage
Reduces the data being consumed through the API when more than one Lifecycle stage is commonly used by setting the specific stageId for which success metrics are retrieved.
Allowed values: source , build , stage-release , release , operate
Property: successMetricsStageId
Default: null
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"successMetricsStageId": "stage-release" }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=successMetricsStageId"Lifecycle Properties
Use the following properties to manage the Lifecycle solution-specific configuration.
Retention of Scan Files (recommended)
The default (null) behavior will delete the previous scan files whenever a new scan is done.
When set to withReports the previous scan files are retained. Scan files are managed with their associated report files during the Data Retention clean-up process.
See Promote Scan REST API to learn more.
Property: purgeScanFiles
Default: null; Supports: withReports and null.
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"purgeScanFiles": "withReports" }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=purgeScanFiles"Enable Observed License Detection for ALP
Enables observed license detection for additional ecosystems for users of Lifecycle with Advanced Legal Pack (ALP) add-on. This setting was set to false for IQ Server versions installed before release 165 but newer instances default to true.
Property: alpObservedLicenseDetectionEnabled
Default: true
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"alpObservedLicenseDetectionEnabled": true }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=alpObservedLicenseDetectionEnabled"Repository Firewall Properties
Use the following properties to manage the Repository Firewall solution-specific configuration.
Set the Custom Quarantine Message
The custom quarantined message to display when a component fails a Repository Firewall policy. This message may be up to 500 chars and include URLs.
See Custom Quarantine Message to learn more.
Property: quarantinedItemCustomMessage
Default: null
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"quarantinedItemCustomMessage": "This is a custom message." }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=quarantinedItemCustomMessage"Automatic Quarantine Release
Set the frequently the Repository Firewall checks components quarantined in the past 14 days for updated metadata.
Scheduling interval (in minutes) for Automatic Quarantine Release. The minimum value supported is 30 minutes.
Property: automaticQuarantineReleaseTimeIntervalInMinutes
Default: 60
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"automaticQuarantineReleaseTimeIntervalInMinutes": 120 }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=automaticQuarantineReleaseTimeIntervalInMinutes"Expiration Time for Temporary Quarantine Reports
Expiration time for quarantine reports
Property: quarantinedComponentReportExpirationTimeInHours
Default: 12
curl -u admin:admin123 -X PUT -H "Content-Type: application/json" -d '{"quarantinedComponentReportExpirationTimeInHours": 2 }' http://localhost:8070/api/v2/config
curl -u admin:admin123 -X GET "https://localhost:8070/api/v2/config?property=quarantinedComponentReportExpirationTimeInHours"Property | Default | Released |
|---|---|---|
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
| ||
|