All pages
Powered by GitBook
2 of 10

HQ

This page describe the Lenses Agent configuration.

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

EULA

To accept the Lenses EULA, set the following in the lenses.conf file:

Without accepting the EULA the Agent will not start! See License.

It has the following top level groups:

Name
Required
Default
Type
Description

http

Yes

n/a

HTTPConfig

Configures everything involving the HTTP.

agents

Yes

n/a

AgentsConfig

Controls the agent handling.

database

Yes

n/a

DatabaseConfig

Configures database settings.

logger

Yes

n/a

LoggerConfig

Sets the logger behaviour.

metrics

Yes

n/a

MetricsConfig

Controls the metrics settings.

license

Yes

n/a

License

Holds the license key.

auth

Yes

n/a

AuthConfig

Configures authentication and authorisation

AuthConfig

Configures authentication and authorisation.

It has the following fields:

Name
Required
Default
Type
Description

administrators

No

[]

strings

Grants root access to principals.

saml

no

n/a

SAMLConfig

Contains SAML2 IdP configuration.

users

no

[]

Array

Creates initial users for password based authentication.

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 for its structure.

HTTPConfig

Configures everything involving the HTTP.

It has the following fields:

Name
Required
Default
Type
Description

address

Yes

n/a

string

Sets the address the HTTP server listens at.

accessControlAllowOrigin

No

["*"]

strings

Sets the value of the "Access-Control-Allow-Origin" header.

accessControlAllowCredentials

No

false

boolean

Sets the value of the "Access-Control-Allow-Credentials" header.

secureSessionCookies

No

true

boolean

Sets the "Secure" attribute on session cookies.

tls

Yes

n/a

TLSConfig

Contains TLS configuration.

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:

Name
Required
Default
Type
Description

metadata

Yes

n/a

string

Contains the IdP issued XML metadata blob.

baseURL

Yes

n/a

string

Defines base URL of HQ for IdP redirects.

uiRootURL

No

/

string

Controls where to redirect to upon successful authentication.

entityID

Yes

n/a

string

Defines the Entity ID.

groupAttributeKey

No

groups

string

Sets the attribute name for group names.

userCreationMode

No

manual

string

Controls how the creation of users should be handled in relation to SSO information.

groupMembershipMode

No

manual

string

Controls how the management of a user's group membership should be handled in relation to SSO information.

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.

AgentsConfig

Controls the agent handling.

It has the following fields:

Name
Required
Default
Type
Description

address

Yes

n/a

string

Sets the address the agent server listens at.

tls

Yes

n/a

TLSConfig

Contains TLS configuration.

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.

TLSConfig

Contains TLS configuration.

It has the following fields:

Name
Required
Default
Type
Description

enabled

Yes

n/a

boolean

Enables or disables TLS.

cert

No

``

string

Sets the PEM formatted public certificate.

key

No

``

string

Sets the PEM formatted private key.

verboseLogs

No

false

boolean

Enables verbose TLS logging.

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:

Name
Required
Default
Type
Description

host

Yes

n/a

string

Sets the name of the host to connect to.

username

No

``

string

Sets the username to authenticate as.

password

No

``

string

Sets the password to authenticate as.

database

Yes

n/a

string

Sets the database to use.

schema

No

``

string

Sets the schema to use.

TLS

No

false

boolean

Enables TLS.

params

No

{}

DBConnectionParams

Provides fine-grained control.

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:

Name
Required
Default
Type
Description

mode

Yes

n/a

string

Controls the format of the logger's output.

level

No

info

string

Controls the level of the logger.

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:

Name
Required
Default
Type
Description

prometheusAddress

No

:9090

string

Sets the Prometheus address.

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.

License: key

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

License: acceptEULA

Accepts the Lenses EULA.

Configuration Reference

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

EULA

To accept the Lenses EULA, set the following in the lenses.conf file:

Without accepting the EULA the Agent will not start! See License.

It has the following top level groups:

Name
Required
Default
Type
Description

http

Yes

n/a

HTTPConfig

Configures everything involving the HTTP.

agents

Yes

n/a

AgentsConfig

Controls the agent handling.

database

Yes

n/a

DatabaseConfig

Configures database settings.

logger

Yes

n/a

LoggerConfig

Sets the logger behaviour.

metrics

Yes

n/a

MetricsConfig

Controls the metrics settings.

license

Yes

n/a

License

Holds the license key.

auth

Yes

n/a

AuthConfig

Configures authentication and authorisation

AuthConfig

Configures authentication and authorisation.

It has the following fields:

Name
Required
Default
Type
Description

administrators

No

[]

strings

Grants root access to principals.

saml

no

n/a

SAMLConfig

Contains SAML2 IdP configuration.

users

no

[]

Array

Creates initial users for password based authentication.

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 for its structure.

HTTPConfig

Configures everything involving the HTTP.

It has the following fields:

Name
Required
Default
Type
Description

address

Yes

n/a

string

Sets the address the HTTP server listens at.

accessControlAllowOrigin

No

["*"]

strings

Sets the value of the "Access-Control-Allow-Origin" header.

accessControlAllowCredentials

No

false

boolean

Sets the value of the "Access-Control-Allow-Credentials" header.

secureSessionCookies

No

true

boolean

Sets the "Secure" attribute on session cookies.

tls

Yes

n/a

TLSConfig

Contains TLS configuration.

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:

Name
Required
Default
Type
Description

metadata

Yes

n/a

string

Contains the IdP issued XML metadata blob.

baseURL

Yes

n/a

string

Defines base URL of HQ for IdP redirects.

uiRootURL

No

/

string

Controls where to redirect to upon successful authentication.

entityID

Yes

n/a

string

Defines the Entity ID.

groupAttributeKey

No

groups

string

Sets the attribute name for group names.

userCreationMode

No

manual

string

Controls how the creation of users should be handled in relation to SSO information.

groupMembershipMode

No

manual

string

Controls how the management of a user's group membership should be handled in relation to SSO information.

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.

AgentsConfig

Controls the agent handling.

It has the following fields:

Name
Required
Default
Type
Description

address

Yes

n/a

string

Sets the address the agent server listens at.

tls

Yes

n/a

TLSConfig

Contains TLS configuration.

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.

TLSConfig

Contains TLS configuration.

It has the following fields:

Name
Required
Default
Type
Description

enabled

Yes

n/a

boolean

Enables or disables TLS.

cert

No

``

string

Sets the PEM formatted public certificate.

key

No

``

string

Sets the PEM formatted private key.

verboseLogs

No

false

boolean

Enables verbose TLS logging.

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:

Name
Required
Default
Type
Description

host

Yes

n/a

string

Sets the name of the host to connect to.

username

No

``

string

Sets the username to authenticate as.

password

No

``

string

Sets the password to authenticate as.

database

Yes

n/a

string

Sets the database to use.

schema

No

``

string

Sets the schema to use.

TLS

No

false

boolean

Enables TLS.

params

No

{}

DBConnectionParams

Provides fine-grained control.

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:

Name
Required
Default
Type
Description

mode

Yes

n/a

string

Controls the format of the logger's output.

level

No

info

string

Controls the level of the logger.

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:

Name
Required
Default
Type
Description

prometheusAddress

No

:9090

string

Sets the Prometheus address.

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.

License: key

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

License: acceptEULA

Accepts the Lenses EULA.

API reference

Users

get

Returns all users

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-04-08T07:13:11.664Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "last_seen_at": "2025-04-08T07:13:11.664Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

post

Creates a new user.

Authorizations
Body
namestring · min: 1 · max: 100required

Sets the unique name of the new user. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150optional

Sets the display name of the new user. If not provided, the value of "name" will be used.

metadataobjectoptional

Allows attaching custom string key/values to resources. The following maxima apply:

  • 50 keys/values;
  • 40 bytes key length;
  • 500 bytes value length.

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/users' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

get

Returns a specific user

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/users/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

patch

Updates a user.

Authorizations
Path parameters
namestringrequired
Body

Updates a user. Absent fields are left untouched.

display_namestring · min: 1 · max: 150optional

Updates the display name of the user.

metadataobjectoptional

Patches metadata. It has the following semantics:

  • Absent keys are left untouched;
  • Null values are deleted;
  • Non-null values are replaced.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/users/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

delete

Deletes a user.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/users/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Successful deletion.

patch

Allows updating fields of the user profile.

Authorizations
Path parameters
namestringrequired
Body

Allows changes of a user's Profile. Absent fields are left untouched.

full_namestring · max: 100optional

Contains the users' full name, e.g. Mary Jane Doe.

email_addressstring · max: 100optional

Contains the users' email address, e.g. mary.jane@doe.net. Note that this is not necessarily the same as the user's name, which often looks like an email address, but is not per se.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/users/{name}/profile' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "full_name": "text",
    "email_address": "text"
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

put

Assigns the given user exactly to the provided groups, ensuring they are not part of any other groups.

Authorizations
Path parameters
namestringrequired

The name of the user.

Body

Defines the groups a user or service account should be exactly a member of.

add_to_groupsstring[]optional

Adds the user or service account to the groups (specified by their names).

remove_from_groupsstring[]optional

Removes the user or service account from the groups (specified by their names). If a group is specified in both add_to_groups as well in here, removal wins.

set_groupsstring[]optional

Sets the user or service account memberships to those groups (specified by their names) in an absolute fashion (ensures user/sa will be exactly a member of those), if provided. Cannot be combined with the add_to_groups or remove_from_groups.

Responses
curl -L \
  --request PUT \
  --url 'https://api.example.com/api/v1/users/{name}/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "add_to_groups": [
      "text"
    ],
    "remove_from_groups": [
      "text"
    ],
    "set_groups": [
      "text"
    ]
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

User groups membership updated successfully.

get

Returns the currently authenticated user

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/users/me' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "profile": {
    "full_name": "text",
    "email_address": "text"
  },
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

post

Starts a session given a username/password and puts it into a cookie.

Authorizations
Body

Bundles a username/password for authentication purposes.

usernamestringrequired
passwordstringrequired
Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/login' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "username": "text",
    "password": "text"
  }'
No Content

Happy response. A set-cookie header will be present.

delete

Deletes all sessions associated with the current user.

Authorizations
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/users/me/sessions' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Happy response.

Groups

get

Lists all groups

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

post

Creates a new Group.

Authorizations
Body
namestring · hq-resource-name · min: 1 · max: 63required

Sets the unique name of the new group. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150optional

Sets the display name of the new group. If not provided, the value of "name" will be used.

descriptionstring · max: 250optional

Sets the description of the new group.

membersstring[]optional

Lists principal names (users, service accounts) to be member of this group.

rolesstring[]optional

Sets the Roles that are bound to this Group by name.

metadataobjectoptional

Allows attaching custom string key/values to resources. The following maxima apply:

  • 50 keys/values;
  • 40 bytes key length;
  • 500 bytes value length.

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "description": "text",
    "members": [
      "text"
    ],
    "roles": [
      "text"
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

get

Gets a group by its name.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/groups/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

patch

Updates a group.

Authorizations
Path parameters
namestringrequired
Body
display_namestring · min: 1 · max: 150optional

Updates the display name of the group.

descriptionstring · max: 250optional

Updates the Group description, if a value is provided.

rolesstring[]optional

Sets the Roles that are bound to this Group to the Roles (specified by their names), if provided.

add_membersstring[]optional

Adds the users/principals (specified by their names) to this group, if provided.

remove_membersstring[]optional

Removes the users/principals (specified by their names) from this group, if provided. If members are specified in both add_members as well in here, removal wins.

set_membersstring[]optional

Sets the members of this group to those users/principals (specified by their names) in an absolute fashion, if provided. Cannot be combined with the add_members or remove_members fields.

metadataobjectoptional

Patches metadata. It has the following semantics:

  • Absent keys are left untouched;
  • Null values are deleted;
  • Non-null values are replaced.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/groups/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "description": "text",
    "roles": [
      "text"
    ],
    "add_members": [
      "text"
    ],
    "remove_members": [
      "text"
    ],
    "set_members": [
      "text"
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "roles": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "users": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "profile": {
        "full_name": "text",
        "email_address": "text"
      },
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "service_accounts": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

delete

Deletes a group.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/groups/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Successful deletion.

Roles

get

Returns all roles.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/roles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "policy_length": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

post

Creates a new role.

Authorizations
Body

Contains the fields needed to create a role.

namestring · hq-resource-name · min: 1 · max: 63required

Sets the unique name of the new role. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150optional

Sets the display name of the new role. If not provided, the value of "name" will be used.

policyobject[]required

Contains a list of permission statements.

metadataobjectoptional

Allows attaching custom string key/values to resources. The following maxima apply:

  • 50 keys/values;
  • 40 bytes key length;
  • 500 bytes value length.

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/roles' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "policy": [
      {
        "action": "kafka:ListTopics",
        "resource": "text",
        "effect": "allow"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

get

Returns a specific role.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

patch

Updates a role.

Authorizations
Path parameters
namestringrequired
Body

Updates a role. Absent fields are left untouched.

display_namestring · min: 1 · max: 150optional

Updates the display name of the role.

policyobject[]optional

Sets, if specififed, the new permission statements.

metadataobjectoptional

Patches metadata. It has the following semantics:

  • Absent keys are left untouched;
  • Null values are deleted;
  • Non-null values are replaced.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "policy": [
      {
        "action": "kafka:ListTopics",
        "resource": "text",
        "effect": "allow"
      }
    ],
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "policy": [
    {
      "action": "kafka:ListTopics",
      "resource": "text",
      "effect": "allow"
    }
  ],
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

delete

Deletes a role.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/roles/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Successful deletion.

Service Accounts

put

Assigns the given service account exactly to the provided groups, ensuring they are not part of any other groups.

Authorizations
Path parameters
namestringrequired

The name of the service account.

Body

Defines the groups a user or service account should be exactly a member of.

add_to_groupsstring[]optional

Adds the user or service account to the groups (specified by their names).

remove_from_groupsstring[]optional

Removes the user or service account from the groups (specified by their names). If a group is specified in both add_to_groups as well in here, removal wins.

set_groupsstring[]optional

Sets the user or service account memberships to those groups (specified by their names) in an absolute fashion (ensures user/sa will be exactly a member of those), if provided. Cannot be combined with the add_to_groups or remove_from_groups.

Responses
curl -L \
  --request PUT \
  --url 'https://api.example.com/api/v1/service-accounts/{name}/groups' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "add_to_groups": [
      "text"
    ],
    "remove_from_groups": [
      "text"
    ],
    "set_groups": [
      "text"
    ]
  }'
{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-04-08T07:13:11.664Z",
  "token_expired": true,
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Service account groups membership updated successfully.

post

Renews the service account's token. The current token is invalidated and a new one is generated. An optional expiration timestamp can be provided.

Authorizations
Path parameters
namestringrequired
Body
token_expires_atstring · date-timeoptional

Determines the moment of token expiration. If not specified, the token will never expire.

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/service-accounts/{name}/renew-token' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "token_expires_at": "2025-04-08T07:13:11.664Z"
  }'
{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-04-08T07:13:11.664Z",
  "token_expired": true,
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "token": "text"
}

Happy response.

delete

Deletes a ServiceAccount.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/service-accounts/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Successful deletion.

patch

Updates a service account.

Authorizations
Path parameters
namestringrequired
Body

Updates a service account. Absent fields are left untouched.

display_namestring · min: 1 · max: 150optional

Updates the display name of the service account.

descriptionstring · max: 250optional

Updates the description of a service account.

metadataobjectoptional

Patches metadata. It has the following semantics:

  • Absent keys are left untouched;
  • Null values are deleted;
  • Non-null values are replaced.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/service-accounts/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "text",
    "description": "text",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-04-08T07:13:11.664Z",
  "token_expired": true,
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

get

Returns a specific ServiceAccount.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/service-accounts/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-04-08T07:13:11.664Z",
  "token_expired": true,
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

post

Creates a new ServiceAccount.

Authorizations
Body
namestring · hq-resource-name · min: 1 · max: 63required

Sets the unique name of the new service account. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150optional

Sets | the display name of the new service account. If not provided, the value of "name" will be used.

descriptionstring · max: 250optional

Sets the description of the new service account.

token_expires_atstring · date-timeoptional

Determines the moment of token expiration. If not specified, the token will never expire.

metadataobjectoptional

Allows attaching custom string key/values to resources. The following maxima apply:

  • 50 keys/values;
  • 40 bytes key length;
  • 500 bytes value length.

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/service-accounts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "description": "text",
    "token_expires_at": "2025-04-08T07:13:11.664Z",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "id": "text",
  "lrn": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "description": "text",
  "groups": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "user_count": 1,
      "sa_count": 1,
      "role_count": 1,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ],
  "token_expires_at": "2025-04-08T07:13:11.664Z",
  "token_expired": true,
  "last_seen_at": "2025-04-08T07:13:11.664Z",
  "is_admin": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "token": "text"
}

Happy response.

get

Returns all ServiceAccounts.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/service-accounts' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "id": "text",
      "lrn": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "description": "text",
      "groups": [
        {
          "name": "text",
          "display_name": "text",
          "lrn": "text",
          "id": "text",
          "created_at": "2025-04-08T07:13:11.664Z",
          "description": "text",
          "user_count": 1,
          "sa_count": 1,
          "role_count": 1,
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          }
        }
      ],
      "token_expires_at": "2025-04-08T07:13:11.664Z",
      "token_expired": true,
      "last_seen_at": "2025-04-08T07:13:11.664Z",
      "is_admin": true,
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

Environments

get

Lists all environments

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "items": [
    {
      "name": "text",
      "display_name": "text",
      "lrn": "text",
      "id": "text",
      "created_at": "2025-04-08T07:13:11.664Z",
      "tier": "development",
      "status": {
        "agent_connected": true,
        "agent": {
          "updated_at": "2025-04-08T07:13:11.664Z",
          "roundtrip_duration": 1,
          "agent": {
            "hostname": "text",
            "version": "text"
          },
          "metrics": {
            "kafka": {
              "version": "text",
              "num_brokers": 1,
              "updated_at": "2025-04-08T07:13:11.664Z"
            },
            "data": {
              "num_topics": 1,
              "num_partitions": 1,
              "num_schemas": 1,
              "num_policies": 1,
              "topic_data_total_bytes": 1,
              "data_in_bytes_per_sec": 1,
              "data_out_bytes_per_sec": 1,
              "data_in_messages_per_sec": 1,
              "updated_at": "2025-04-08T07:13:11.664Z"
            },
            "apps": {
              "num_consumers": 1,
              "num_other_apps": 1,
              "updated_at": "2025-04-08T07:13:11.664Z"
            },
            "connect": {
              "num_clusters": 1,
              "num_connectors": 1,
              "updated_at": "2025-04-08T07:13:11.664Z"
            },
            "other": {
              "num_issues": 1,
              "updated_at": "2025-04-08T07:13:11.664Z"
            }
          }
        }
      },
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      }
    }
  ]
}

Happy response.

post

Creates a new environment.

Authorizations
Body
namestring · hq-resource-name · min: 1 · max: 63required

Sets the name of the new environment. It must be a valid HQ resource name: it can only contain lowercase alphanumeric characters or hyphens; hyphens cannot appear at the end or start; the length is 63 characters at most.

display_namestring · min: 1 · max: 150optional

Sets the display name of the new environment. If not provided, the value of "name" will be used.

tierstring · enumrequired

Enumerates Tiers.

Available options:
metadataobjectoptional

Allows attaching custom string key/values to resources. The following maxima apply:

  • 50 keys/values;
  • 40 bytes key length;
  • 500 bytes value length.

Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/environments' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "display_name": "text",
    "tier": "development",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-04-08T07:13:11.664Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "data": {
          "num_topics": 1,
          "num_partitions": 1,
          "num_schemas": 1,
          "num_policies": 1,
          "topic_data_total_bytes": 1,
          "data_in_bytes_per_sec": 1,
          "data_out_bytes_per_sec": 1,
          "data_in_messages_per_sec": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "agent_key": "text"
}

Happy response.

get

Retrieves a single environment by name.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-04-08T07:13:11.664Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "data": {
          "num_topics": 1,
          "num_partitions": 1,
          "num_schemas": 1,
          "num_policies": 1,
          "topic_data_total_bytes": 1,
          "data_in_bytes_per_sec": 1,
          "data_out_bytes_per_sec": 1,
          "data_in_messages_per_sec": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

patch

Updates an environment.

Authorizations
Path parameters
namestringrequired
Body
tierstring · enumoptional

Enumerates Tiers.

Available options:
metadataobjectoptional

Patches metadata. It has the following semantics:

  • Absent keys are left untouched;
  • Null values are deleted;
  • Non-null values are replaced.

display_namestring · min: 1 · max: 150optional

Updates the display name of the environment.

Responses
curl -L \
  --request PATCH \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "tier": "development",
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "display_name": "text"
  }'
{
  "name": "text",
  "display_name": "text",
  "lrn": "text",
  "id": "text",
  "created_at": "2025-04-08T07:13:11.664Z",
  "tier": "development",
  "status": {
    "agent_connected": true,
    "agent": {
      "updated_at": "2025-04-08T07:13:11.664Z",
      "roundtrip_duration": 1,
      "agent": {
        "hostname": "text",
        "version": "text"
      },
      "metrics": {
        "kafka": {
          "version": "text",
          "num_brokers": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "data": {
          "num_topics": 1,
          "num_partitions": 1,
          "num_schemas": 1,
          "num_policies": 1,
          "topic_data_total_bytes": 1,
          "data_in_bytes_per_sec": 1,
          "data_out_bytes_per_sec": 1,
          "data_in_messages_per_sec": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "apps": {
          "num_consumers": 1,
          "num_other_apps": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "connect": {
          "num_clusters": 1,
          "num_connectors": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        },
        "other": {
          "num_issues": 1,
          "updated_at": "2025-04-08T07:13:11.664Z"
        }
      }
    }
  },
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

Happy response.

delete

Deletes an environment.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --request DELETE \
  --url 'https://api.example.com/api/v1/environments/{name}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
No Content

Successful deletion.

get

Provides Server-Sent Events (SSE) for environment updates. TODO.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/live/sse' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

Error object.

get

Proxies HTTP to a Lenses instance. Note: this is not a regular HTTP API endpoint. The path specified here is a prefix. Everything beneath it gets proxied to the corresponding Lenses instance. Any request body and method (the GET here is only a placeholder) are accepted, as long as the Lenses API accepts it. The connection can even be upgraded to a websocket. The status code and response body are controlled by the Lenses API. This concept does not fit into the OpenAPI world at all; this definition is only here for the sake of documentation to avoid having an undocumented dark matter API.

Authorizations
Path parameters
namestringrequired
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "type": "not_found",
  "title": "text",
  "status": 1,
  "invalid_fields": [
    {
      "name": "text",
      "error": "reference_not_found",
      "title": "text"
    }
  ],
  "sso_url": "text",
  "request_id": "text"
}

Error object.

get

Retrieves a list of datasets

Authorizations
Path parameters
namestringrequired
Query parameters
pageintegeroptional

The page number to be returned, must be greater than zero. Defaults to 1.

Example: 1
pageSizeintegerrequired

The elements amount on a single page, must be greater than zero.

Example: 25
querystringoptional

A search keyword to match dataset, fields and description against.

Example: name
connectionsstring[]optional

A list of connection names to filter by. All connections will be included when no value is supplied.

tagsstring[]optional

A list of tag names to filter by. All tags will be included when no value is supplied.

sortBystring · enumoptional

The field to sort results by

Available options:
sortingOrderstring · enumoptional

Sorting order. Defaults to ascending

Available options:
includeSystemEntitiesbooleanoptional

A flag to include in the search also system entities (e.g. Kafka's __consumer_offsets topic).

includeMetadatabooleanoptional

Whether to search only by table name, or also to include field names/documentation (defaults to true)

formatstring[]optional

Schema format. Relevant only when sourceType is SchemaRegistrySubject

hasRecordsbooleanoptional

Filter based on whether the dataset has records

compactedbooleanoptional

Filter based on compacted. Relevant only when sourceType is Kafka

Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets?pageSize=1' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "datasets": {
    "values": [
      {
        "name": "text",
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "records": 1,
        "recordsPerSecond": 1,
        "keyType": "text",
        "valueType": "text",
        "connectionName": "text",
        "replication": 1,
        "consumers": 1,
        "partitions": 1,
        "fields": {
          "key": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 1,
                  "endIndex": 1,
                  "arrayIndex": 1
                }
              ],
              "isNullable": true,
              "default": "text"
            }
          ],
          "value": [
            {
              "name": "text",
              "type": "text",
              "typeDetails": {
                "lensesDataType": "text"
              },
              "description": "text",
              "ancestors": [
                "text"
              ],
              "highlights": [
                {
                  "fieldName": "text",
                  "startIndex": 1,
                  "endIndex": 1,
                  "arrayIndex": 1
                }
              ],
              "isNullable": true,
              "default": "text"
            }
          ]
        },
        "isSystemEntity": true,
        "isMarkedForDeletion": true,
        "isCompacted": true,
        "sizeBytes": 1,
        "policies": [
          {
            "policyId": "text",
            "policyName": "text",
            "policyCategory": "text",
            "obfuscation": "text",
            "matchingKeyFields": [
              {
                "name": "text",
                "parents": [
                  "text"
                ]
              }
            ],
            "matchingValueFields": [
              {
                "name": "text",
                "parents": [
                  "text"
                ]
              }
            ]
          }
        ],
        "permissions": [
          "text"
        ],
        "description": "text",
        "tags": [
          {
            "name": "text",
            "count": 1
          }
        ],
        "retentionMs": 1,
        "retentionBytes": 1,
        "backupRestoreState": {},
        "sourceType": "text"
      }
    ],
    "pagesAmount": 1,
    "totalCount": 1
  },
  "sourceTypes": [
    "Kafka"
  ]
}

A response wrapping a paginated list of datasets and the set of relative source types

get

Get a single dataset by connection/name. While information mastered externally might be a few second out of sync with their respective sources (e.g. JMX metadata, Elasticsearch index status, etc), information mastered in Lenses's db is guaranteed to be up to date (e.g. tags, descriptions).

Authorizations
Path parameters
namestringrequired
connectionstringrequiredExample: kafka
datasetstringrequiredExample: customer-positions
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/{connection}/{dataset}' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "name": "text",
  "highlights": [
    {
      "fieldName": "text",
      "startIndex": 1,
      "endIndex": 1,
      "arrayIndex": 1
    }
  ],
  "records": 1,
  "recordsPerSecond": 1,
  "keyType": "text",
  "valueType": "text",
  "connectionName": "text",
  "replication": 1,
  "consumers": 1,
  "partitions": 1,
  "fields": {
    "key": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "isNullable": true,
        "default": "text"
      }
    ],
    "value": [
      {
        "name": "text",
        "type": "text",
        "typeDetails": {
          "lensesDataType": "text"
        },
        "description": "text",
        "ancestors": [
          "text"
        ],
        "highlights": [
          {
            "fieldName": "text",
            "startIndex": 1,
            "endIndex": 1,
            "arrayIndex": 1
          }
        ],
        "isNullable": true,
        "default": "text"
      }
    ]
  },
  "isSystemEntity": true,
  "isMarkedForDeletion": true,
  "isCompacted": true,
  "sizeBytes": 1,
  "policies": [
    {
      "policyId": "text",
      "policyName": "text",
      "policyCategory": "text",
      "obfuscation": "text",
      "matchingKeyFields": [
        {
          "name": "text",
          "parents": [
            "text"
          ]
        }
      ],
      "matchingValueFields": [
        {
          "name": "text",
          "parents": [
            "text"
          ]
        }
      ]
    }
  ],
  "permissions": [
    "text"
  ],
  "description": "text",
  "tags": [
    {
      "name": "text",
      "count": 1
    }
  ],
  "retentionMs": 1,
  "retentionBytes": 1,
  "backupRestoreState": {},
  "sourceType": "text"
}
get

Retrieves a list of dataset tags

Authorizations
Path parameters
namestringrequired
Query parameters
querystringoptional

Get tags sorted by dataset count

Example: user
Responses
curl -L \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/datasets/tags' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "tags": [
    {
      "name": "text",
      "count": 1
    }
  ]
}

A response wrapping a paginated list of datasets and the set of relative source types

post

Returns the intellisense result for a given query

Authorizations
Path parameters
namestringrequired
Body
sqlstringrequired
caretintegeroptional
connectorIdstringoptional
Responses
curl -L \
  --request POST \
  --url 'https://api.example.com/api/v1/environments/{name}/proxy/api/v1/sql/presentation' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "sql": "text",
    "caret": 1,
    "connectorId": "text"
  }'
{
  "input": "text",
  "caret": 1,
  "lints": [
    {
      "start": 1,
      "end": 1,
      "text": "text",
      "type": "Warning"
    }
  ],
  "suggestions": [
    {
      "display": "text",
      "text": "text",
      "start": 1,
      "end": 1,
      "type": "text",
      "description": "text",
      "highlightStart": 1,
      "highlightEnd": 1
    }
  ],
  "highlights": [
    {
      "start": 1,
      "end": 1,
      "text": "text",
      "type": "Keyword"
    }
  ],
  "tables": [
    {
      "tableName": {
        "value": "text"
      },
      "fields": [
        {
          "value": "text"
        }
      ]
    }
  ],
  "statementsPositions": [
    {
      "index": 1,
      "start": 1,
      "end": 1
    }
  ]
}

Happy response

License

get

Returns HQ's licence summary.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/licence-summary' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "is_community": true
}

Successfully returns licence response.

get

Returns HQ's licence.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/licence' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "expires_at": "2025-04-08T07:13:11.664Z",
  "tier": "community"
}

Successfully returns licence response.

Meta

get

Returns the backend's settings information.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/settings' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "api": {
    "saml": {
      "user_creation_mode": "manual",
      "users_group_membership_management_mode": "manual"
    }
  }
}

Successfully returns application settings response.

get

Returns the backend's meta information.

Authorizations
Responses
curl -L \
  --url 'https://api.example.com/api/v1/meta-info' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'
{
  "version": "text",
  "build_id": "text",
  "backend_build_id": "text",
  "ui_build_id": "text",
  "goos": "text",
  "goarch": "text",
  "started_at": "2025-04-08T07:13:11.664Z",
  "memstats_alloc": 1,
  "memstats_sys": 1,
  "gc_cpu_fraction": 1,
  "num_goroutine": 1
}

Happy response.