KeepHQ availability is limited; if it is missing from Builtin Connections, ask your workspace administrator about access.
Prerequisites
- A self-hosted Keep instance and permission to create API keys.
- An HTTPS route from CloudThinker to your Keep backend. For CloudThinker Cloud, see Reaching private services. For a self-hosted deployment of CloudThinker, allow access from your deployment.
- The Admin role in your CloudThinker workspace. See Roles.
localhost or through your SSH tunnel does not make its API reachable from CloudThinker. For disposable testing, a temporary public HTTPS tunnel can forward to the authenticated API; remove it afterward.
Setup
1
Identify the backend address
Find your Keep API’s HTTPS origin, such as
https://keep-api.example.com. This can differ from the UI address. Include a port if required, but no UI path or /alerts.2
Create a dedicated API key
In Keep, open Settings → API Keys and create a key. Enter a Name, such as
cloudthinker, and select a Role covering the required permissions. Click Create API Key and copy the key.Available roles depend on your Keep authentication setup; ask your Keep administrator for the narrowest suitable role.3
Add the connection in CloudThinker
Open More → Workspace settings → Connections, stay on Builtin Connections, and select KeepHQ. Enter API URL and API key. Leave CA certificate (optional) empty for publicly trusted HTTPS; otherwise paste your private CA certificate in PEM format.Click Connect. CloudThinker reads a small sample of stored alerts through Keep’s REST API with
X-API-KEY authentication.Success state: KeepHQ shows a Connected status. This verifies alert access only; run the verification prompt below to check the other reads.Connection details
Certificate and hostname verification always remain on. CloudThinker refuses redirects, so enter the exact backend origin rather than an address that redirects to it.
Required permissions
The key’s role must cover these Keep API permissions:Agent capabilities
The connection does not pull fresh data from providers, change incidents, execute workflows, or administer providers. Topology describes stored relationships, not live network reachability. Results are limited samples; alert counts describe returned occurrences, not all alerts.
Verify the connection
Example prompts
Troubleshooting
API key rejected
API key rejected
Create a replacement key and update API key in the connection.
Missing alert permission
Missing alert permission
The key’s role lacks alert access. Other failed reads need their matching permissions from the table above.
Wrong API address
Wrong API address
Check API URL points to the backend, not the UI, and remove any path. A redirect also fails: use the final HTTPS origin directly.
Certificate verification failed
Certificate verification failed
Check the certificate matches the API hostname. For a private issuer, paste its CA certificate into CA certificate (optional). If PEM is rejected, copy the complete certificate, including its BEGIN and END lines.
API unreachable
API unreachable
Check DNS, firewall rules, and the route from CloudThinker to the API host and port. Access through your browser or local SSH tunnel alone is insufficient.
Rate limit reached
Rate limit reached
Wait before reconnecting or repeating the request.
Security
- Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
- Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
- Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
- Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.
- Keep API authentication enabled, including behind a testing tunnel, and restrict network access to CloudThinker where possible.
- After a topology write times out or cannot be verified, inspect current topology before retrying to avoid repeating a change.
Related
Connections
Manage credentials and reach private services.
Approvals
Control which topology changes can run.