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

#### Example

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

#### Response

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.

#### Example

```
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/config
```

#### Response

A 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}
```

#### Example

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

#### Response

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](https://owasp.org/www-community/attacks/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 shown 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&amp;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](https://help.sonatype.com/en/waived-component-upgrades.html "Waived Component Upgrades") 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](https://help.sonatype.com/en/sbom-search.html#advanced-search-215923 "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](https://help.sonatype.com/en/advanced-search-rest-api.html "Advanced Search REST 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 Advanced Reporting Insights

Allows IQ Server to send non-anonymized telemetry data to Sonatype for Advanced Reporting Insights. This data is used to display application names in Enterprise Reporting. Disabling this property can result in obfuscated application names and a degraded Enterprise Reporting 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`, `proxy`, `compliance`.

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](https://help.sonatype.com/en/promote-scan-rest-api.html "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"
```

### Enforce Minimum Integration Versions

Defines how many of the most recent Sonatype integration versions are permitted to perform policy evaluations. When configured, only the latest N integration versions can initiate evaluations. Requests from older versions will fail validation.

This setting helps ensure that all integrations used in your organization include recent capabilities and compatibility with the latest Lifecycle features. If not configured, all integration versions are accepted. Re-evaluations and evaluations started directly from the Lifecycle UI are not subject to version validation.

Property: `integrationsSupportedVersionCount`

Default: `null`

**Constraints**

- Must be a positive integer (greater than 0).

**Examples**

Set

```
curl -u admin:admin123 -X PUT \
  -H "Content-Type: application/json" \
  -d '{"integrationsSupportedVersionCount": 5}' \
  http://localhost:8070/api/v2/config
```

Get

```
curl -u admin:admin123 -X GET \
  "http://localhost:8070/api/v2/config?property=integrationsSupportedVersionCount"
```

Delete

```
curl -u admin:admin123 -X DELETE \
  "http://localhost:8070/api/v2/config?property=integrationsSupportedVersionCount"
```

## 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](https://help.sonatype.com/en/custom-quarantine-messages.html "Custom Quarantine Messages") 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"
```

## List of Supported Properties

| Property | Default | Released |
| --- | --- | --- |
| #### advancedSearchCSVExportDelimiter | `,` (a comma) |  |
| #### ADVANCED_REPORTING_INSIGHTS_ENABLED | `true` |  |
| #### alpObservedLicenseDetectionEnabled | `true` |  |
| #### apiAccessAllowList | `null` |  |
| #### automaticQuarantineReleaseTimeIntervalInMinutes | `60` |  |
| #### baseUrl | `null` |  |
| #### consumerMaxQueuedRows | `30` |  |
| #### consumerPeriodInMilliseconds | `300000` (5 minutes) |  |
| #### consumerRowExpirationInMilliseconds | `6000000` (100 minutes) |  |
| #### consumerThreadsPerTenant | `1` |  |
| #### csrfProtection | `true` |  |
| #### cyclePeriodInMilliseconds | `86400000` (24 hours) |  |
| #### eventBus.maxThreadPoolSize | `500` |  |
| #### evaluationQueueConfig | [Evaluation Queue Configuration](https://help-test.sonatype.com/en/sbom-continuous-monitoring.html#evaluation-queue-configuration) |  |
| #### forceBaseUrl | `false` |  |
| #### frameAncestorsAllowlist | `null` |  |
| #### hdsUrl | `https://clm.sonatype.com/` |  |
| #### maxAdvancedSearchClauseCount | `2048` |  |
| #### policyMonitoringHour | `0` (hour of the day 0-23) |  |
| #### producerMaxQueuedRows | `1000` |  |
| #### producerPeriodInMilliseconds | `600000` (10 minutes) |  |
| #### purgeScanFiles | `null` |  |
| #### quarantinedComponentReportExpirationTimeInHours | `12` |  |
| #### quarantinedItemCustomMessage | `null` |  |
| #### resetCycleTimeout | `false` |  |
| #### sessionTimeout | `30` |  |
| #### startTimeDelayEnabled | `true` |  |
| #### successMetricsStageId | `null` |  |
| #### userAgentSuffix | `null` |  |
| #### waivedComponentUpgradeMonitoringEnabled | `false` |  |
| #### webhookSecretPassphrase | `^d1swM!FF&amp;qQ` |  |