> ## Documentation Index
> Fetch the complete documentation index at: https://docs.changeguard.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Managing API key authentication for agents and CI/CD

## 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.

<Warning>
  The full API key is shown only at creation. Copy it immediately and store it securely — you cannot retrieve it later.
</Warning>

You can also create keys via the API:

```bash theme={null}
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

| Scope   | Permissions                                 | Use For                            |
| ------- | ------------------------------------------- | ---------------------------------- |
| `agent` | Push snapshots, push logs, ArgoCD discovery | Cluster agents                     |
| `cicd`  | Deployment validation (`/api/validate`)     | GitHub Actions, GitLab CI, Jenkins |
| `full`  | All API access                              | Administrative scripts             |

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

## 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