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

​
Authenticating requests

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