Skip to main content
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

PrefixScopeAllowed operations
ck_live_read_writeAll operations: plan, apply, create, update, delete
ck_ro_read_onlyRead-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

export CHARLEY_API_KEY=ck_live_...
agent-charley-cli plan --file policies/

​
CLI flag

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: 
agent-charley-cli --env-file .env.staging plan --file policies/

​
Python SDK

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: 
env:
  CHARLEY_API_KEY: ${{ secrets.CHARLEY_API_KEY }}
Add the secret under Settings → Secrets and variables → Actions. GitLab CI: 
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

StatusMeaning
401Key is missing, invalid, expired, or revoked
403Read-only key attempted a write operation