Authorization: Bearer ... header.
Key model
Scopes
A key created with only a name has full access: it can call everything, including operations added later. To limit a key, list the scopes it may use when you create it. Scopes are fixed at creation, so to change them create a new key and revoke the old one.preset instead of scopes to use a ready-made list. The key stores the expanded scopes, and you cannot send both fields.
A request that needs a scope the key doesn’t hold fails with
403 and the code SCOPE_REQUIRED. The error names the missing scopes. GET /api/v1/auth/me returns the scopes of the key you’re calling with.
Scopes apply to API keys only. Dashboard sessions follow organization roles.
Authenticating requests
Every request tohttps://api.devhelm.io/api/v1/* needs a bearer token. Send x-phelm-org-id for the organization the key belongs to. x-phelm-workspace-id selects one of that organization’s workspaces:
x-phelm-workspace-id to use the organization’s default workspace, the one created with the org. A workspace id from another organization is rejected with 403. See the authentication reference for the full header contract and error codes.
Managing keys
- Dashboard
- CLI
- REST API
- Open Settings → API Keys.
- Click Create API Key, give it a descriptive name, and optionally set an expiration.
- Copy the token value from the modal — this is the only time it will be shown.
- Store it in your secret manager (1Password, AWS Secrets Manager, GitHub Actions secret, etc.).
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):key value. Regenerating a revoked key is rejected.
Zero-downtime roll — for consumers you can’t update atomically, overlap old and new:
- Create a new key with a descriptive name.
- Update the consuming system (CI variable, Kubernetes secret, Terraform variable) to use the new value.
- Wait for the consumer to redeploy and confirm via the key’s
lastUsedAtthat the new key is being used. - Revoke the old key.
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
lastUsedAttimestamp shows whether it is still being exercised after the consumer was rolled. - Never commit keys to source control. Use
${SECRET_NAME}substitution indevhelm.ymland pull from your secret manager in CI. - Use the secrets vault 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
Authentication reference
Header contract, error codes, and token formats.
api-keys CLI
Manage keys from the command line.
Secrets
Outbound credential storage for monitor checks.
Patterns: errors
Auth-related error codes and how to handle them.