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

# Authentication

> Authenticate API requests with an API key in the x-api-key header. Dashboard access uses GitHub OAuth.

# Authentication

## API requests

All API requests require an API key passed in the `x-api-key` header:

```bash theme={null}
curl https://api.docex.dev/v1/whoami \
  -H "x-api-key: dx_live_..."
```

<Warning>
  Do not use `Authorization: Bearer` — Docex uses `x-api-key` exclusively.
</Warning>

## Obtaining an API key

API keys are generated during `docex setup` or from the dashboard:

1. Run `docex setup --use-case "..." --top-up 5`
2. Approve the setup session in the browser (GitHub auth + wallet top-up)
3. The CLI returns the API key once — copy it immediately

## Dashboard authentication

The web dashboard uses GitHub OAuth. For local development, create a GitHub OAuth App with:

* Homepage URL: `https://docex.dev`
* Authorization callback URL: `https://api.docex.dev/v1/auth/github/callback`

Set `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` in the API environment. Without them, local development falls back to a handle-based mock login.

## Environment variables

| Variable         | Required | Description                                        |
| ---------------- | -------- | -------------------------------------------------- |
| `DOCEX_API_KEY`  | Yes      | Your API key from `docex setup`                    |
| `DOCEX_BASE_URL` | No       | API base URL (defaults to `http://localhost:4000`) |