# Configuration Reference

HQ's configuration is defined in the **config.yaml** file.

It has the following top level groups:

<table data-full-width="false"><thead><tr><th width="138">Name</th><th width="99">Required</th><th width="95">Default</th><th width="191">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>http</code></td><td>Yes</td><td>n/a</td><td><a href="#httpconfig"><code>HTTPConfig</code></a></td><td>Configures everything involving the HTTP.</td></tr><tr><td><code>agents</code></td><td>Yes</td><td>n/a</td><td><a href="#agentsconfig"><code>AgentsConfig</code></a></td><td>Controls the agent handling.</td></tr><tr><td><code>database</code></td><td>Yes</td><td>n/a</td><td><a href="#databaseconfig"><code>DatabaseConfig</code></a></td><td>Configures database settings.</td></tr><tr><td><code>logger</code></td><td>Yes</td><td>n/a</td><td><a href="#loggerconfig"><code>LoggerConfig</code></a></td><td>Sets the logger behaviour.</td></tr><tr><td><code>metrics</code></td><td>Yes</td><td>n/a</td><td><a href="#metricsconfig"><code>MetricsConfig</code></a></td><td>Controls the metrics settings.</td></tr><tr><td><code>license</code></td><td>Yes</td><td>n/a</td><td><a href="#license"><code>License</code></a></td><td>Holds the license key.</td></tr><tr><td><code>auth</code></td><td>Yes</td><td>n/a</td><td><a href="#authconfig"><code>AuthConfig</code></a></td><td>Configures authentication and authorisation</td></tr></tbody></table>

***

## AuthConfig

Configures authentication and authorisation.

It has the following fields:

<table><thead><tr><th width="196">Name</th><th width="100">Required</th><th width="91">Default</th><th width="138">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>administrators</code></td><td>No</td><td><code>[]</code></td><td><code>strings</code></td><td>Grants root access to principals.</td></tr><tr><td><code>saml</code></td><td>no</td><td>n/a</td><td><a href="#samlconfig"><code>SAMLConfig</code></a></td><td>Contains SAML2 IdP configuration.</td></tr><tr><td><code>users</code></td><td>no</td><td>[]</td><td>Array</td><td>Creates initial users for password based authentication.</td></tr></tbody></table>

### AuthConfig: administrators

Lists the names of the principals (users, service accounts) that have root access. Access control allows any API operation performed by such principals. Optional. If not set, it will default to `[]`.

### AuthConfig: saml

Contains SAML2 IdP configuration. Please refer [here](https://github.com/lensesio-dev/hq-backend/blob/master/docs/config.md#samlconfig) for its structure.

### AuthConfig: OAuth

Contains OAuth configuration.

These fields apply under `auth.oauth2.authorizationServer`.

<table data-full-width="false"><thead><tr><th width="214">Name</th><th width="103">Required</th><th width="102">Default</th><th width="122">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Yes</td><td><code>false</code></td><td><code>boolean</code></td><td>Master switch.</td></tr><tr><td><code>issuerURL</code></td><td>Conditional</td><td><code>""</code></td><td><code>string</code></td><td>Required when enabled. Must match the URL clients use to reach HQ.</td></tr><tr><td><code>grantLifetime</code></td><td>No</td><td><code>2160h</code></td><td><code>duration</code></td><td>Token lifetime. Default is 90 days.</td></tr><tr><td><code>requirePKCE</code></td><td>No</td><td><code>true</code></td><td><code>boolean</code></td><td>Enforces PKCE for OAuth 2.1 compliance.</td></tr><tr><td><code>dcr</code></td><td>No</td><td><code>false</code></td><td><code>boolean</code></td><td>Enables Dynamic Client Registration for self-registering clients such as Claude.</td></tr><tr><td><code>unauthenticatedIntrospection</code></td><td>No</td><td><code>false</code></td><td><code>boolean</code></td><td>Dev-only escape hatch.</td></tr></tbody></table>

***

## HTTPConfig

Configures everything involving the HTTP.

It has the following fields:

<table data-full-width="false"><thead><tr><th width="179">Name</th><th width="102">Required</th><th width="91">Default</th><th width="132">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>address</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Sets the address the HTTP server listens at.</td></tr><tr><td><code>accessControlAllowOrigin</code></td><td>No</td><td><code>["*"]</code></td><td><code>strings</code></td><td>Sets the value of the "Access-Control-Allow-Origin" header.</td></tr><tr><td><code>accessControlAllowCredentials</code></td><td>No</td><td><code>false</code></td><td><code>boolean</code></td><td>Sets the value of the "Access-Control-Allow-Credentials" header.</td></tr><tr><td><code>secureSessionCookies</code></td><td>No</td><td><code>true</code></td><td><code>boolean</code></td><td>Sets the "Secure" attribute on session cookies.</td></tr><tr><td><code>tls</code></td><td>Yes</td><td>n/a</td><td><a href="#tlsconfig"><code>TLSConfig</code></a></td><td>Contains TLS configuration.</td></tr></tbody></table>

### HTTPConfig: address

Sets the address the HTTP server listens at.

Example value: `127.0.0.1:80`.

### HTTPConfig: accessControlAllowOrigin

Sets the value of the "Access-Control-Allow-Origin" header. This is only relevant when serving the backend from a different origin than the UI. Optional. If not set, it will default to `["*"]`.

### HTTPConfig: accessControlAllowCredentials

Sets the value of the "Access-Control-Allow-Credentials" header. This is only relevant when serving the backend from a different origin than the UI. Optional. If not set, it will default to `false`.

### HTTPConfig: secureSessionCookies

Sets the "Secure" attribute on authentication session cookies. When set, a browser sends such cookies not over unsecured HTTP (expect for localhost). If running Lenses HQ over unsecured HTTP, set this to false. Optional. If not set, it will default to `true`.

### HTTPConfig: tls

Contains TLS configuration. Please refer here for its structure.

***

## SAMLConfig

Contains SAML2 IdP configuration.

It has the following fields:

<table data-full-width="false"><thead><tr><th width="239">Name</th><th width="109">Required</th><th width="101">Default</th><th width="128">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Yes</td><td>false</td><td><code>boolean</code></td><td>Enables or disables SAML.</td></tr><tr><td><code>metadata</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Contains the IdP issued XML metadata blob.</td></tr><tr><td><code>baseURL</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Defines base URL of HQ for IdP redirects.</td></tr><tr><td><code>uiRootURL</code></td><td>No</td><td><code>/</code></td><td><code>string</code></td><td>Controls where to redirect to upon successful authentication.</td></tr><tr><td><code>entityID</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Defines the Entity ID.</td></tr><tr><td><code>groupAttributeKey</code></td><td>No</td><td><code>groups</code></td><td><code>string</code></td><td>Sets the attribute name for group names.</td></tr><tr><td><code>userCreationMode</code></td><td>No</td><td><code>manual</code></td><td><code>string</code></td><td>Controls how the creation of users should be handled in relation to SSO information.</td></tr><tr><td><code>groupMembershipMode</code></td><td>No</td><td><code>manual</code></td><td><code>string</code></td><td>Controls how the management of a user's group membership should be handled in relation to SSO information.</td></tr><tr><td><code>authnRequestSignature</code></td><td>No</td><td><ul class="contains-task-list"><li><input type="checkbox"></li></ul></td><td><a href="#samlconfig-authrequestsignature"><code>ARSConfig</code></a></td><td>Enables signing the AuthnRequest that HQ sends to the IdP</td></tr></tbody></table>

### SAMLConfig: metadata

Contains the IdP issued XML metadata blob.

Example value: `<?xml version="1.0" ... (big blob of xml) </md:EntityDescriptor>`.

### SAMLConfig: baseURL

Defines the base URL of Lenses HQ; the IdP redirects back to here on success.

Example value: `https://hq.example.com`.

### SAMLConfig: uiRootURL

Controls where the backend redirects to after having received a valid SAML2 assertion. Optional. If not set, it will default to `/`.

Example value: `/`.

### SAMLConfig: entityID

Defines the Entity ID.

Example value: `https://hq.example.com`.

### SAMLConfig: groupAttributeKey

Sets the attribute name from which group names are extracted in the SAML2 assertions. Different providers use different names. Okta, Keycloak and Google use "groups". OneLogin uses "roles". Azure uses "<http://schemas.microsoft.com/ws/2008/06/identity/claims/groups>". Optional. If not set, it will default to `groups`.

Example value: `groups`.

### SAMLConfig: userCreationMode

Controls how the creation of users should be handled in relation to SSO information. With the 'manual' mode, only users that currently exist in HQ can login. Users that do not exist are rejected. With the 'sso' mode, users that do not exist are automatically created. Allowed values are `manual` or `sso`. Optional. If not set, it will default to `manual`.

### SAMLConfig: groupMembershipMode

Controls how the management of a user's group membership should be handled in relation to SSO information. With the 'manual' mode, the information about the group membership returned from an Identity Provider will not be used and a user will only be a member of groups that were explicitly assigned to him locally. With the 'sso' mode, group information from Identity Provider (IdP) will be used. On login, a user's group membership is set to the groups listed in the IdP. Groups that do not exist in HQ are ignored. Allowed values are `manual` or `sso`. Optional. If not set, it will default to `manual`.

### SAMLConfig: authRequestSignature

<table data-full-width="false"><thead><tr><th width="125">Name</th><th width="85">Required</th><th width="84">Default</th><th width="147">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Yes</td><td>true</td><td><code>string</code></td><td>Sets the address the agent server listens at.</td></tr><tr><td><code>cert</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>String 'cert' sets the PEM formatted AuthnRequest signing certificate. If provided, the key needs to be provided as well. If not provided while AuthnRequest signing is enabled, HQ will generate a key-pair on start.</td></tr><tr><td><code>key</code></td><td>No</td><td>n/a</td><td><code>string</code></td><td>String 'key' sets the PEM formatted AuthnRequest signing private key. If provided, the cert needs to be provided as well. If not provided while AuthnRequest signing is enabled, HQ will generate a key-pair on start.</td></tr></tbody></table>

## AgentsConfig

Controls the agent handling.

It has the following fields:

<table data-full-width="false"><thead><tr><th width="125">Name</th><th width="85">Required</th><th width="84">Default</th><th width="147">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>address</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Sets the address the agent server listens at.</td></tr><tr><td><code>tls</code></td><td>Yes</td><td>n/a</td><td><a href="#tlsconfig"><code>TLSConfig</code></a></td><td>Contains TLS configuration.</td></tr><tr><td><code>grpc</code></td><td>No</td><td>n/a</td><td><a href="#agentgrpcconfig"><code>AgentGRPCConfig</code></a></td><td>Contains Agent gRPC configuration</td></tr></tbody></table>

### AgentsConfig: address

Sets the address the agent server listens at.

Example value: `127.0.0.1:3000`.

### AgentsConfig: tls

Contains TLS configuration. Please refer here for its structure.

***

## AgentGrpcConfig

Contains Agent gRPC configuration. This configuration section is optional. If not provided, its values are set to the defaults described in its \[structure]

| Name                    | Required | Default    | Type      | Description                                                                 |
| ----------------------- | -------- | ---------- | --------- | --------------------------------------------------------------------------- |
| `apiMaxRecvMessageSize` | No       | `33554432` | `integer` | Overrides the default maximum body size in bytes for proxied API responses. |

***

## TLSConfig

Contains TLS configuration.

It has the following fields:

<table data-full-width="false"><thead><tr><th width="164">Name</th><th width="107">Required</th><th width="93">Default</th><th width="116">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>enabled</code></td><td>Yes</td><td>n/a</td><td><code>boolean</code></td><td>Enables or disables TLS.</td></tr><tr><td><code>cert</code></td><td>No</td><td>``</td><td><code>string</code></td><td>Sets the PEM formatted public certificate.</td></tr><tr><td><code>key</code></td><td>No</td><td>``</td><td><code>string</code></td><td>Sets the PEM formatted private key.</td></tr><tr><td><code>verboseLogs</code></td><td>No</td><td><code>false</code></td><td><code>boolean</code></td><td>Enables verbose TLS logging.</td></tr></tbody></table>

### TLSConfig: enabled

Enables or disables TLS.

Example value: `false`.

### TLSConfig: cert

Sets the PEM formatted public certificate. Optional. If not set, it will default to \`\`.

Example value: `-----BEGIN CERTIFICATE----- EXampLeRanDoM ... -----END CERTIFICATE-----` .

### TLSConfig: key

Sets the PEM formatted private key. Optional. If not set, it will default to \`\`.

Example value: `-----BEGIN PRIVATE KEY----- ExAmPlErAnDoM ... -----END PRIVATE KEY-----` .

### TLSConfig: verboseLogs

Enables additional logging of TLS settings and events at debug level. The information presented might be a bit too much for day to day use but can provide extra information for troubleshooting TLS configuration. Optional. If not set, it will default to `false`.

***

## DatabaseConfig

Configures database settings.

It has the following fields:

<table><thead><tr><th width="143">Name</th><th width="106">Required</th><th width="90">Default</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>host</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Sets the name of the host to connect to.</td></tr><tr><td><code>username</code></td><td>No</td><td>``</td><td><code>string</code></td><td>Sets the username to authenticate as.</td></tr><tr><td><code>password</code></td><td>No</td><td>``</td><td><code>string</code></td><td>Sets the password to authenticate as.</td></tr><tr><td><code>database</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Sets the database to use.</td></tr><tr><td><code>schema</code></td><td>No</td><td>``</td><td><code>string</code></td><td>Sets the schema to use.</td></tr><tr><td><code>TLS</code></td><td>No</td><td><code>false</code></td><td><code>boolean</code></td><td>Enables TLS.</td></tr><tr><td><code>params</code></td><td>No</td><td><code>{}</code></td><td><code>DBConnectionParams</code></td><td>Provides fine-grained control.</td></tr></tbody></table>

### DatabaseConfig: host

Sets the name of the host to connect to. A comma-separated list of host names is also accepted; each host name in the list is tried in order.

Example value: `postgres:5432`.

### DatabaseConfig: username

Sets the username to authenticate as. Optional. If not set, it will default to \`\`.

Example value: `johhnybingo`.

### DatabaseConfig: password

Sets the password to authenticate as. Optional. If not set, it will default to \`\`.

Example value: `my-password`.

### DatabaseConfig: database

Sets the database to use.

Example value: `my-database`.

### DatabaseConfig: schema

Sets the schema to use. Optional. If not set, it will default to "".

Example value: `my-schema`.

### DatabaseConfig: TLS

Enables TLS. In PostgreSQL connection string terms, setting TLS to `false` corresponds to `sslmode=disable`; setting TLS to `true` corresponds to `sslmode=verify-full`. For more fine-grained control, specify `sslmode` in the params which takes precedence. Optional. If not set, it will default to `false`.

Example value: `true`.

### DatabaseConfig: params

Contains connection string parameters as key/values pairs. It allow fine-grained control of connection settings. The parameters can be found here: <https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS> Optional. If not set, it will default to `{}`.

Example value: `{"application_name":"example"}`.

## LoggerConfig

Sets the logger behaviour.

It has the following fields:

<table data-full-width="false"><thead><tr><th width="135">Name</th><th width="114">Required</th><th width="89">Default</th><th width="112">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>mode</code></td><td>Yes</td><td>n/a</td><td><code>string</code></td><td>Controls the format of the logger's output.</td></tr><tr><td><code>level</code></td><td>No</td><td><code>info</code></td><td><code>string</code></td><td>Controls the level of the logger.</td></tr></tbody></table>

### LoggerConfig: mode

Controls the format of the logger's output. Allowed values are `text` or `json`.

### LoggerConfig: level

Controls the level of the logger. Allowed values are `info` or `debug`. Optional. If not set, it will default to `info`.

## MetricsConfig

Controls the metrics settings.

It has the following fields:

<table data-full-width="false"><thead><tr><th width="229">Name</th><th width="117">Required</th><th width="93">Default</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>prometheusAddress</code></td><td>No</td><td><code>:9090</code></td><td><code>string</code></td><td>Sets the Prometheus address.</td></tr></tbody></table>

### MetricsConfig: prometheusAddress

Sets the address at which Prometheus metrics are served. Optional. If not set, it will default to `:9090`.

## License

Holds the license key.

It has the following fields:

| Name       | Required | Default | Type     | Description                                               |
| ---------- | -------- | ------- | -------- | --------------------------------------------------------- |
| `key`      | Yes      | n/a     | `string` | Sets the license key.                                     |
| acceptEULA | Yes      | fals    | boolean  | Accepts the [Lenses EULA.](https://lenses.io/legals/eula) |

#### License: key

Sets the license key. An HQ key starts with "license*key*".

#### **License: acceptEULA**

Accepts the Lenses EULA.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/deployment/configuration/hq/configuration-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.