Skip to main content
Detail supports two authentication methods: API keys for programmatic and CI/CD access, and a browser-based login flow for interactive use with the CLI. Both grant access according to your organization’s permissions.

​
API keys

​
Create an API key

To generate an API key, open app.detail.dev and navigate to Settings → API Keys. Click New API key, give it a descriptive name, and copy the key value immediately — Detail only shows the full key once.

​
Key format

All Detail API keys are prefixed with dtl_live_ so you can identify them at a glance and avoid accidentally committing them alongside other secrets.

​
Using your API key

Pass your API key as a Bearer token in the Authorization header of every request: 
curl https://api.detail.dev/public/v1/user \
  -H "Authorization: Bearer dtl_live_YOUR_KEY_HERE"
A successful response returns your email address and organization memberships, confirming the key is valid: 
{
  "email": "[email protected]",
  "orgs": [
    {
      "id": "org_abc123",
      "name": "your-org"
    }
  ]
}
Keep your API key secret. Never commit it to source control or expose it in client-side code. If a key is compromised, rotate it immediately from Settings → API Keys in the dashboard — delete the old key and generate a new one.

​
CLI authentication

​
Log in with the browser flow

The Detail CLI uses a browser-based OAuth flow by default. Run the following command to open the authorization page in your browser: 
detail auth login
Your browser opens app.detail.dev, where you approve the CLI’s access request. Once you approve, the CLI receives a token automatically and stores it locally. You don’t need to copy or paste anything.

​
Skip the browser with --token

If you’re working in a headless environment (such as a CI runner or a remote server), pass your API key directly using the --token flag: 
detail auth login --token dtl_live_YOUR_KEY_HERE
This writes the token to the local config file without opening a browser.

​
Token storage

The CLI stores your authentication token at: 
~/.config/detail-cli/config.toml
This file is created automatically on first login and is read on every CLI invocation. Do not share or commit this file.

​
Check authentication status

To verify that the CLI is authenticated and see which account it’s using, run: 
detail auth status
The command prints your authenticated email address and organization. If the CLI is not authenticated or the token is invalid, it prints an error and exits with a non-zero code.

​
Log out

To remove your stored credentials, run: 
detail auth logout
This deletes the token from ~/.config/detail-cli/config.toml. You’ll need to run detail auth login again before making any further CLI requests.

​
Authentication errors

If a request fails for an authentication or authorization reason, the Detail API returns a structured error response: 
{
  "type": "DETAIL_AUTHENTICATION_ERROR",
  "message": "Invalid or missing API token.",
  "statusCode": 401
}
The two most common error codes are:
HTTP statusError typeCause
401 UnauthorizedDETAIL_AUTHENTICATION_ERRORThe token is missing, malformed, or has been revoked.
403 ForbiddenAUTHORIZATION_ERRORThe token is valid but does not have permission to access the requested resource.
If you’re unsure whether your token is working, run detail auth status in the CLI or make a test request to GET https://api.detail.dev/public/v1/user. A 200 response confirms the token is valid and shows your account details. A 401 means you need to generate a new key from Settings → API Keys.