Skip to main content

​
Overview

API keys authenticate agents (the Edge collector, the remediation executor) and non-GitHub CI/CD integrations with the ChangeGuard AI backend. Keys start with cg_ and are bcrypt-hashed before storage — ChangeGuard AI never stores or logs plaintext keys.
GitHub needs no API key. The GitHub Action authenticates with a short-lived identity token GitHub issues to the workflow, verified by ChangeGuard AI against the repository connection you created. See Connect GitHub.

​
Creating Keys

Go to Settings → API Keys → Create Key in the dashboard. Choose a name and scope, then click Create Key. The full key is displayed once.
The full API key is shown only at creation. Copy it immediately and store it securely — you cannot retrieve it later.
You can also create keys via the API:

​
Scopes

Follow the principle of least privilege. Use agent scope for agents and cicd scope for pipeline integrations. Reserve full scope for admin tooling only.

​
How Authentication Works

  1. The agent or CI tool sends the X-API-Key header with every request
  2. The backend extracts the key prefix (first 10 characters) for fast lookup
  3. The full key is verified against the bcrypt hash stored in the database
  4. The tenant context is derived from the key — agents don’t need to know their tenant ID
  5. The key’s scope is checked against the endpoint’s required scope

​
Revoking Keys

Go to Settings → API Keys and click Revoke next to the key. You can also revoke a key by its ID (from the keys list) via the API:
Revocation takes effect across the ChangeGuard AI control plane once the revoke request succeeds. The request returns success only after the revocation is durably recorded; from that moment every backend replica rejects the key on its next request — with no grace period, cache delay, restart, or propagation wait.

​
Key Rotation

Rotate keys without downtime:
  1. Create a new key with the same scope
  2. Update the agent’s Kubernetes Secret with the new key value
  3. Restart the agent deployment (kubectl rollout restart)
  4. Verify the agent reconnects (check backend logs for Ingested messages)
  5. Revoke the old key

​
Security Details

  • Keys are hashed with bcrypt (cost factor 10) before storage
  • Only the key prefix (cg_xxxxxxxx) is visible in the dashboard — never the full key
  • Keys are scoped per tenant — a key from one tenant cannot authenticate against another
  • Revocation is durable and takes effect control-plane-wide the instant the revoke request succeeds — every replica re-checks revocation against the database on every request, so a revoked key cannot survive on a warm replica, a restart, or a second node
  • Failed API key attempts are logged with source IP for monitoring