KeySkopePreview · Reviewed 2026-10-08
Preview: implemented and tested with fixtures shaped like the documented API responses.
Before you start
- A ClickHouse Cloud organization and an organization admin who can create roles and API keys.
- Your organization ID (Organization details in the ClickHouse Cloud console).
Read-only permissions
Create a custom role (Users and roles → Create new role) with exactly these permissions, then create an API key on that role:
| Permission | Used for |
|---|---|
| Access organization | Organization name and the health check. |
| Manage members / roles / settings | The member list and each member’s roles. ClickHouse shows the member list only to this permission. KeySkope never uses it to change anything: the connector sends read requests only. |
| View API keys | API keys, their roles, state and last use. Never the key secret. |
| View audit logs | Administrative events: role changes, invitations, IP access list and password changes. |
Give the key an expiry and a source-IP restriction, and record its owner in your credential register. Do not grant service, database or billing permissions for this connector.
Connect ClickHouse Cloud
- In ClickHouse Cloud, open Users and roles and create the custom role above.
- Open API keys, create a key on that role with an expiry and IP restriction, and copy the key ID and secret.
- Copy the organization ID.
- In KeySkope, open Data sources → Add data source → ClickHouse Cloud, enter the three fields and save. The first sync starts straight away.
Connection fields
| Setting | Purpose / value |
|---|---|
| org_id | Organization ID. |
| key_id | API key ID. |
| key_secret | API key secret. Stored per tenant in the secret store; never shown again and never logged. |
What appears in KeySkope
- Every member with every role they hold. A member can hold several roles; each is its own access row.
- Built-in roles carry KeySkope’s summary of what they allow; Admin, Service Admin and Service API Admin count as privileged. ClickHouse does not publish custom role definitions through its API, so custom roles show definition not available.
- API keys as non-human accounts with their roles and last use. Keys have no owner field in ClickHouse; give each one an owner in KeySkope.
- Pending invitations, with flags for invitations older than 14 days and expired ones.
- Each member’s last administrative action from the audit log, and security-relevant changes from the last 90 days.
- Not available at organization level: member sign-ins and queries. Activity shows as not collected, so no member is ever reported as dormant from this connector. Database-level access and last query need the per-service layer (planned).
- If a sync cannot read the member list, nothing is removed.
Verify the first sync
- Check that Accounts and Roles show complete and Activity shows not collected.
- Compare the member count and one admin’s roles with Users and roles in ClickHouse.
- Check the API keys list against the console, and give each key an owner.
Troubleshooting
| Symptom | Cause / fix |
|---|---|
| 401 | Wrong key ID or secret, or the key has expired. |
| 403 on members | The role is missing Manage members / roles / settings. |
| Audit events missing | Add View audit logs. Members, roles and keys still sync without it. |
| Request blocked | The key’s IP restriction does not include KeySkope’s egress address. |