> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devhelm.io/llms.txt
> Use this file to discover all available pages before exploring further.
# API Keys
> Create, rotate, and scope DevHelm API keys for CLI, SDK, and API access
API keys authenticate machine-to-machine requests against the DevHelm REST API. The CLI, both SDKs, the MCP server, the Terraform provider, and any custom integration all use the same key format and the same `Authorization: Bearer ...` header.
Looking for human sign-in to the dashboard? That uses Auth0 SSO and is separate from API keys. API keys exist for automation: CI/CD pipelines, services, scripts, and AI agents.
## Key model
| Property | Notes |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scope** | Each key is bound to a single organization. The workspace is selected per request via the `x-phelm-workspace-id` header (defaults to the org's default workspace). |
| **Display name** | Human-readable label shown in the dashboard and audit log. Choose something that identifies the consumer ("CI Pipeline — Backend", "Terraform — prod"). |
| **Expiration** | Optional. If set, the API rejects requests with `401` after the expiration timestamp. Recommended for contractor and short-lived CI tokens. |
| **Revocation** | Soft-delete. The key remains visible in the key list (with `revokedAt` set) but stops authenticating within minutes. Revoked keys can never be reactivated or regenerated. |
| **Visibility** | The `key` value (format `dh_live_...`) is returned at creation time and is also visible to org **admins** in the dashboard and via `GET /api/v1/api-keys`. Treat list access as privileged. |
| **Limit** | Up to 10 API keys per organization. |
## Authenticating requests
Every request to `https://api.devhelm.io/api/v1/*` needs three pieces:
```http theme={null}
Authorization: Bearer dh_live_...
x-phelm-org-id: 1
x-phelm-workspace-id: 1
```
The org and workspace headers default to those embedded in the key, so for single-workspace setups you only need the bearer token. See the [authentication reference](/authentication) for the full header contract and error codes.
## Managing keys
1. Open **Settings → API Keys**.
2. Click **Create API Key**, give it a descriptive name, and optionally set an expiration.
3. Copy the token value from the modal — this is the only time it will be shown.
4. Store it in your secret manager (1Password, AWS Secrets Manager, GitHub Actions secret, etc.).
```bash theme={null}
devhelm api-keys create --name "CI Pipeline" --expires-at "2026-12-31T00:00:00Z"
devhelm api-keys list
devhelm api-keys revoke 42
```
Full command reference: [`devhelm api-keys`](/cli/commands/api-keys).
```bash theme={null}
curl -X POST https://api.devhelm.io/api/v1/api-keys \
-H "Authorization: Bearer $DEVHELM_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "CI Pipeline", "expiresAt": "2026-12-31T00:00:00Z"}'
```
The response body carries the new key in the `key` field, alongside `id`, `name`, `createdAt`, and `expiresAt`.
## Rotation
There are two ways to rotate a key:
**In-place regenerate** — swaps the key value while keeping the same id, name, and expiration. The old value stops working as soon as the auth cache clears (within \~5 minutes):
```bash theme={null}
curl -X POST https://api.devhelm.io/api/v1/api-keys//regenerate \
-H "Authorization: Bearer $DEVHELM_API_TOKEN"
```
The response contains the new `key` value. Regenerating a revoked key is rejected.
**Zero-downtime roll** — for consumers you can't update atomically, overlap old and new:
1. Create a new key with a descriptive name.
2. Update the consuming system (CI variable, Kubernetes secret, Terraform variable) to use the new value.
3. Wait for the consumer to redeploy and confirm via the key's `lastUsedAt` that the new key is being used.
4. Revoke the old key.
Setting an `expiresAt` on every key effectively forces a rotation cadence.
## Security best practices
* **One key per consumer.** Don't share a single token across multiple CI jobs or services. Per-consumer keys make audit logs and revocation surgical.
* **Set an expiration on every key.** Even production keys benefit from a yearly rotation cadence.
* **Revoke (or regenerate) immediately on suspected leak.** Each key's `lastUsedAt` timestamp shows whether it is still being exercised after the consumer was rolled.
* **Never commit keys to source control.** Use `${SECRET_NAME}` substitution in [`devhelm.yml`](/mac/yaml/file-format) and pull from your secret manager in CI.
* **Use the [secrets vault](/platform/secrets) for credentials your monitors need to call your APIs** — that vault is separate from API keys, and is for outbound auth, not for authenticating to DevHelm.
## Audit log
Every API key event (`api_key.created`, `api_key.revoked`, `api_key.regenerated`, `api_key.deleted`) is recorded in the org's audit log along with the actor and a timestamp. Filter the audit log (`GET /api/v1/audit-log?action=api_key.created`) to review key lifecycle activity.
## Next steps
Header contract, error codes, and token formats.
Manage keys from the command line.
Outbound credential storage for monitor checks.
Auth-related error codes and how to handle them.