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

# API Keys

> Create and manage API keys for the Policy-as-Code CLI and SDK

The Policy-as-Code CLI and Python SDK authenticate with **API keys** — separate from your dashboard login. API keys are created by Org Admins in the dashboard and are scoped to a single org.

## Key Types

| Prefix     | Scope        | Allowed operations                                     |
| ---------- | ------------ | ------------------------------------------------------ |
| `ck_live_` | `read_write` | All operations: plan, apply, create, update, delete    |
| `ck_ro_`   | `read_only`  | Read-only: list, get, effective policy, plan (dry-run) |

Use a read-only key in CI steps that only diff or audit, and a read-write key only in the apply step.

## Creating a Key

1. Go to **Settings → API Keys** in the Charley dashboard.
2. Click **New API Key**.
3. Give it a name (e.g. `"ci-github-actions"`) and choose `read_write` or `read_only`.
4. Optionally set an expiration date.
5. Copy the key immediately — **it is shown only once**.

## Using a Key

### Environment variable (recommended)

```bash theme={null}
export CHARLEY_API_KEY=ck_live_...
agent-charley-cli plan --file policies/
```

### CLI flag

```bash theme={null}
agent-charley-cli --api-key ck_live_... plan --file policies/
```

### dotenv file

Create a `.env` file in your working directory:

```
CHARLEY_API_KEY=ck_live_...
CHARLEY_ENV=prod
```

The CLI auto-loads `.env` by default. Use `--env-file` to point at a different file:

```bash theme={null}
agent-charley-cli --env-file .env.staging plan --file policies/
```

### Python SDK

```python theme={null}
from charley_policy import CharleyClient

client = CharleyClient(api_key="ck_live_...")
# or: CharleyClient()  # reads CHARLEY_API_KEY from environment
```

## Storing Keys in CI

**GitHub Actions:**

```yaml theme={null}
env:
  CHARLEY_API_KEY: ${{ secrets.CHARLEY_API_KEY }}
```

Add the secret under **Settings → Secrets and variables → Actions**.

**GitLab CI:**

```yaml theme={null}
variables:
  CHARLEY_API_KEY: $CHARLEY_API_KEY   # set in CI/CD Variables settings
```

## Key Rotation

1. Create a new key in the dashboard.
2. Update your secret store (GitHub Actions secret, AWS Secrets Manager, etc.).
3. Verify the new key: `agent-charley-cli --verbose plan --file policies/`
4. Delete the old key in the dashboard.

## Expiration

Keys can expire after 30, 90, 180, or 365 days, or never. The dashboard shows a warning banner 14 days before a key expires. Expired keys return `401 Unauthorized`.

## Security Notes

* The raw key is shown **once** at creation and never stored by Charley.
* Only a SHA-256 hash is stored server-side.
* Dashboard shows only the first 12 characters (prefix) for identification.
* Revoked or deleted keys return `401` immediately.

## Error Responses

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| `401`  | Key is missing, invalid, expired, or revoked |
| `403`  | Read-only key attempted a write operation    |