Skip to main content
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. The workspace is selected per request via the x-phelm-workspace-id header (defaults to the org’s default workspace).
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 the key list (with revokedAt set) but stops authenticating within minutes. Revoked keys can never be reactivated or regenerated.
VisibilityThe 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.
LimitUp to 10 API keys per organization.

​
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 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): 
curl -X POST https://api.devhelm.io/api/v1/api-keys/<id>/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 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.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.