Skip to main content
Detail API keys let you authenticate programmatic access to the Detail REST API and CLI. You can create multiple keys for different environments or team members, and revoke any key instantly if it’s no longer needed or has been compromised.

​
Creating an API key

1

Sign in to Detail

Go to app.detail.dev and sign in.
2

Open API Keys settings

Go to Settings → API Keys.
3

Create a new key

Click New API Key.
4

Name the key

Give the key a descriptive name so you can identify it later — for example, CI pipeline, Local dev, or Staging.
5

Copy the key

Copy the key immediately and store it somewhere safe (for example, your password manager or secrets vault). The full key value is only shown once — if you lose it, you’ll need to create a new one.

​
Key format

Production API keys follow this format:
All Detail API keys are prefixed with dtl_live_ for production environments. This prefix makes it easy to detect keys in code reviews and automated secret scanners.

​
Using API keys

REST API — Pass the key as a Bearer token in the Authorization header:
CLI — Authenticate the Detail CLI with your key using the auth login command:
Once authenticated, the CLI stores the token locally and uses it for all subsequent commands.

​
Revoking a key

1

Open API Keys settings

Go to Settings → API Keys in the Detail dashboard.
2

Find the key to revoke

Locate the key by its name in the list.
3

Revoke it

Click the trash icon next to the key and confirm the revocation.
Revocation is immediate. Any request using the revoked key will return a 401 DETAIL_AUTHENTICATION_ERROR response. There is no grace period.
Never commit API keys to version control — not even in private repositories. Use environment variables or a secrets manager (such as AWS Secrets Manager, HashiCorp Vault, or GitHub Actions secrets) to inject keys at runtime.

​
Best practices

  • One key per environment — create separate keys for CI, staging, and production so you can rotate or revoke them independently without disrupting other workflows.
  • Use descriptive names — name keys after their purpose and owner (e.g., GitHub Actions – prod deploy) so you always know where a key is used before revoking it.
  • Rotate keys periodically — even if a key hasn’t been compromised, rotating it regularly limits the blast radius of an undetected leak.
  • Revoke immediately on compromise — if you suspect a key has been exposed, revoke it right away. Create a replacement key and update the relevant environment variables or secrets before resuming work.