Skip to main content

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

PropertyNotes
ScopeEach key is bound to a single organization and workspace. Switching workspaces requires a different key (or different x-phelm-workspace-id header on a multi-workspace token).
Display nameHuman-readable label shown in the dashboard and audit log. Choose something that identifies the consumer (“CI Pipeline — Backend”, “Terraform — prod”).
ExpirationOptional. If set, the API rejects requests with 401 after the expiration timestamp. Recommended for contractor and short-lived CI tokens.
RevocationSoft-delete. The key remains visible in audit logs but stops authenticating immediately. Revoked keys can never be reactivated.
VisibilityThe full token value is only returned once, at creation time. After that the dashboard and API only expose a prefix (first 8 chars) for identification.

​
Authenticating requests

Every request to https://api.devhelm.io/api/v1/* needs three pieces: 
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 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.).

​
Rotation

There is no in-place “rotate” operation — rotation is always create new key → roll consumers → revoke old key:
  1. Create a new key with the same scope.
  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 in the audit log that the new key is being used.
  4. Revoke the old key.
Setting an expiresAt on every key effectively forces a rotation cadence, and the dashboard surfaces a warning banner 14 days before expiry.

​
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 immediately on suspected leak. The dashboard’s audit log shows recent IPs and user-agents; cross-reference if a key may have been exposed.
  • Never commit keys to source control. Use ${SECRET_NAME} substitution in devhelm.yml and 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.deleted) is recorded in the org’s audit log along with the actor (user or another API key) and a timestamp. Filter the audit log by event type 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.