> ## Documentation Index > Fetch the complete documentation index at: https://docs.oleria.com/llms.txt > Use this file to discover all available pages before exploring further. # ClickHouse Cloud > Connect your ClickHouse Cloud organization to Oleria to continuously discover members, roles, API keys, and audit activity across your cloud analytics database platform. ClickHouse Cloud is a managed analytics database platform. Connect your ClickHouse Cloud organization to Oleria to see who has access to it and what they can do. Oleria reads members, roles, API keys, and the audit log from the ClickHouse Cloud API, so you can find dormant or over-privileged access and act on it from Oleria. ## What Oleria discovers Once connected, Oleria continuously discovers and maps the following from your ClickHouse Cloud organization: * **Accounts** - every member of the organization, with name, email, join date, and assigned roles. Pending invitations appear as disabled accounts that carry the roles the invitation will grant, so outstanding access is visible before anyone accepts it. * **Roles** - the system roles (such as Admin) and your custom roles, which accounts hold each one, and each role's permissions. Oleria marks an account as an administrator when it holds the **Admin** role or a role with `control-plane:organization:manage`. * **Non-human identities (NHIs)** - every organization API key as an API token, with its state, expiration date, last use, IP allow list, and assigned roles. Each key also appears as a credential, linked to the member or key that created it when the audit log records the creation. * **Activity** - organization audit log events, such as member and role changes, API key creation and changes, SAML and approved-domain changes, and service and organization setting changes. Events are attributed to the member or API key that performed them. Oleria refreshes this data on its [regular sync schedule](/integrations/overview.md#sync-model). ## Prerequisites * The **Admin** role in your ClickHouse Cloud organization, to create a custom role and an API key. * Admin access on the Oleria platform to add a new integration. One Oleria integration covers one ClickHouse Cloud organization. To connect several organizations, create an API key in each one and add a separate integration for each. ### Permissions Oleria needs ClickHouse Cloud API keys get their permissions from the roles assigned to them. Assign the key a custom role with these permissions: | Permission | What Oleria uses it for | | :- | :- | | `control-plane:organization:view` | Required. Reads members and pending invitations. Oleria doesn't connect without it. Also needed to remove members and change their roles. | | `control-plane:organization:view-api-keys` | Reads API keys. Without it, Oleria skips API keys and their credentials, and marks the sync as partially completed. Also needed to change an API key's roles or disable it. | | `control-plane:organization:view-activities` | Reads the audit log. Without it, no activity syncs and Oleria marks the sync as partially completed. Members also have no last activity date, and API keys have no creator. | | `control-plane:organization:manage` | Reads roles and their permissions. ClickHouse Cloud has no read-only permission for roles, so this grant also allows changes. Also needed to remove members and change roles. Without it, Oleria lists roles from their assignments only, with no permission detail, and only the **Admin** role counts as administrative. | | `control-plane:organization:update-api-keys` | Needed only for remediation: adding or removing roles, and disabling API keys. | For a read-only sync, `view`, `view-api-keys`, and `view-activities` are enough. Roles and who holds them still appear, but without their permission detail, and the integration's **Capabilities** tab shows **Read roles** as not enabled because ClickHouse Cloud lists roles only for keys with `manage`. Remediation actions aren't available. A key that holds `manage` has administrative access, so Oleria shows its own API key as an administrative non-human identity. The **Admin** system role holds all of these. The **Organization API Reader** system role (called Org API reader in ClickHouse's documentation) isn't enough, because it doesn't include `view-activities` or `manage`. The ClickHouse Cloud role editor lists permissions by name rather than by ID. `control-plane:organization:view` is **Access organization**, and ClickHouse's [audit log documentation](https://clickhouse.com/docs/products/cloud/guides/security/audit-logging/console-audit-log) calls `control-plane:organization:view-activities` **View audit logs**. For the others, pick the permission whose description matches its entry in ClickHouse's [console roles and permissions](https://clickhouse.com/docs/products/cloud/reference/security/console-roles) reference. For example, `view-api-keys` is described as "View API keys for the organization" and `update-api-keys` as "Update existing API keys and their permissions". ## Create an API key in ClickHouse Cloud > [!NOTE] > > The exact location of these settings can change over time. If the steps below don't match what you see, refer to ClickHouse's [custom roles](https://clickhouse.com/docs/products/cloud/guides/security/cloud-access-management/manage-custom-roles) and [API key](https://clickhouse.com/docs/cloud/manage/openapi) documentation. **1. Create a custom role for Oleria** In the ClickHouse Cloud console, select the name of your organization, then select **Users and roles** from the menu. Select the **Roles** tab, then **Create new role**. Name the role (for example, `Oleria`), select **Allow**, and add the organization permissions from the [table above](#permissions-oleria-needs). Select **Create role**. **2. Create an API key** Select **API Keys** in the left menu, then **New API Key**. If the organization has no keys yet, use the prompt to create your first one. Name the key (for example, `oleria`), assign it the custom role you created, and set an expiration date. Select **Generate API Key**. > [!NOTE] > > If you restrict the key under **Allow access to this API Key** -> **Specific locations**, include Oleria's IP addresses. To get them, contact [support@oleria.com](mailto:support@oleria.com). **3. Copy the Key ID and Key secret** Copy the **Key ID** and **Key secret** before you leave the page. You'll paste both into Oleria in the next section. > [!WARNING] > > ClickHouse Cloud shows the Key secret only once. Copy it now and store it securely. Anyone who has the key can act in your organization with the permissions of its role. > [!TIP] > > Use a key dedicated to Oleria. ClickHouse Cloud limits each API key to 10 requests every 10 seconds, and that limit is shared by everything that uses the key. ## Connect ClickHouse Cloud to Oleria **1. Find ClickHouse Cloud in Oleria** Go to your Oleria workspace, select **Integrations**, select the **Available** tab, and search for **ClickHouse Cloud**. **2. Complete the connection form** Select the **ClickHouse Cloud** card and fill in the connection form: | Field | Notes | | :- | :- | | API Key ID | Required. The Key ID of the API key you created. | | API Key Secret | Required. The Key secret of the same API key. | You don't need to enter an organization or a host. Oleria finds the organization the key belongs to. **3. Save the integration** Select **Authenticate**. Oleria checks that the key can read your organization's members before saving the integration. ## Verify the integration Confirm the new instance appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. Oleria names the connection after your ClickHouse Cloud organization. After the first sync completes, you can review the discovered accounts, roles, API keys, and activity in your Oleria workspace. > [!NOTE] > > If you replace or rotate the API key, edit the integration in Oleria and enter both the new **API Key ID** and **API Key Secret**. To keep the current key while editing, leave both fields blank. The new key must belong to the same ClickHouse Cloud organization. To connect a different organization, add a new integration instead. ## Remediation actions Beyond discovery, Oleria can act on ClickHouse Cloud access to remediate risk, using the same API key. Oleria checks that the key has the permissions each action needs before it runs. | Action | What it does | Revert | | :- | :- | :- | | Disable user accounts | Removes the member from the organization. ClickHouse Cloud has no way to suspend a member, so removal is the only way to cut their access. On a pending invitation, this deletes the invitation. | Partial - Oleria sends a new invitation to the same email address with the same roles. The person must accept it to regain access. | | Delete user | Removes the member from the organization. On a pending invitation, this deletes the invitation. | Not supported - invite the person again in ClickHouse Cloud. | | Add user to role | Assigns a role to a member or an API key. | Supported - restores the roles the account held before. | | Remove user from role | Removes a role from a member or an API key. | Supported - restores the roles the account held before. | | Disable NHI accounts | Disables an API key. A disabled key can't call the ClickHouse Cloud API. | Supported - re-enables the key. | Required permissions per action: * **Disable user accounts** and **Delete user** - `control-plane:organization:view` and `control-plane:organization:manage`. * **Add user to role** and **Remove user from role** - `control-plane:organization:view`, `control-plane:organization:manage`, `control-plane:organization:view-api-keys`, and `control-plane:organization:update-api-keys`. * **Disable NHI accounts** - `control-plane:organization:view-api-keys` and `control-plane:organization:update-api-keys`. A few safeguards apply: * Oleria won't remove the last member with administrative permissions, or remove a role if that would leave the organization with no administrator. * Oleria won't remove an account's only role. To cut an API key's access, disable it instead. * Oleria won't disable or change the roles of the API key the integration uses. Doing so would disconnect the integration. * A pending invitation's roles can't be changed. Delete the invitation and invite the person again. * A revert only undoes the change Oleria made. If someone changed the same account or key in ClickHouse Cloud in the meantime, Oleria leaves it as is. A removed member isn't re-invited if they already rejoined or have a pending invitation. ## Known limitations * **Groups aren't discovered.** ClickHouse Cloud has groups only through SCIM, which requires the Enterprise plan and SAML, and each SCIM group maps to a custom role. Oleria shows that access through roles. * **MFA, SSO, and authentication methods aren't available.** The ClickHouse Cloud API doesn't expose them for members, so Oleria reports these fields as unavailable, not as disabled. Changes to MFA methods and SAML connections still appear in activity. * **Password changes aren't available.** The API and the audit log don't report when a member changed their password. * **Member last activity is partial.** ClickHouse Cloud doesn't report when a member last signed in, so Oleria uses the newest audit log event the member performed in the last 30 days. Members who only sign in and view data can appear inactive. API keys have an exact last-used time. * **Members are always shown as enabled.** ClickHouse Cloud has no disabled state for members. A member removed from your SAML identity provider stays in the organization until someone removes them. * **Database users and roles aren't discovered.** Oleria reads the organization's control plane. Database users, roles, and grants inside each service aren't inventoried. * **Services aren't discovered as resources.** Oleria doesn't inventory services, backups, or ClickPipes. Service events still appear in activity. * **SCIM tokens aren't discovered.** ClickHouse Cloud offers no API to list them. * **System and support activity has no linked account.** Audit events performed by ClickHouse system processes or ClickHouse support staff appear without an account. * **API keys only.** ClickHouse Cloud API keys authenticate with a Key ID and Key secret. OAuth isn't supported. ## Contact us For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.