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

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.
Send 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 to https://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:
Omit 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

  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.