Skip to main content

​
Overview

API keys authenticate agents and CI/CD integrations with the ChangeGuard backend. Keys start with cg_ and are bcrypt-hashed before storage — ChangeGuard never stores or logs plaintext keys.

​
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: 
curl -X POST https://api.changeguard.ai/api/keys \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Agent", "scope": "agent"}'

​
Scopes

ScopePermissionsUse For
agentPush snapshots, push logs, ArgoCD discoveryCluster agents
cicdDeployment validation (/api/validate)GitHub Actions, GitLab CI, Jenkins
fullAll API accessAdministrative scripts
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. Revoked keys are rejected immediately on the next request — there is no grace period or cache delay.

​
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 immediate and enforced at the authentication middleware layer
  • Failed API key attempts are logged with source IP for monitoring