> ## Documentation Index
> Fetch the complete documentation index at: https://docs.detail.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and manage Detail API keys

> Generate API keys to authenticate CLI and REST API access, understand the key format, and learn how to rotate or revoke keys safely.

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

<Steps>
  <Step title="Sign in to Detail">
    Go to [app.detail.dev](https://app.detail.dev) and sign in.
  </Step>

  <Step title="Open API Keys settings">
    Go to **Settings → API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **New API Key**.
  </Step>

  <Step title="Name the key">
    Give the key a descriptive name so you can identify it later — for example, `CI pipeline`, `Local dev`, or `Staging`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Key format

Production API keys follow this format:

```text theme={null}
dtl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

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:

```bash theme={null}
curl https://api.detail.dev/public/v1/repos \
  -H "Authorization: Bearer dtl_live_YOUR_KEY"
```

**CLI** — Authenticate the Detail CLI with your key using the `auth login` command:

```bash theme={null}
detail auth login --token dtl_live_YOUR_KEY
```

Once authenticated, the CLI stores the token locally and uses it for all subsequent commands.

## Revoking a key

<Steps>
  <Step title="Open API Keys settings">
    Go to **Settings → API Keys** in the Detail dashboard.
  </Step>

  <Step title="Find the key to revoke">
    Locate the key by its name in the list.
  </Step>

  <Step title="Revoke it">
    Click the trash icon next to the key and confirm the revocation.
  </Step>
</Steps>

Revocation is immediate. Any request using the revoked key will return a `401 DETAIL_AUTHENTICATION_ERROR` response. There is no grace period.

<Warning>
  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.
</Warning>

## 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.