> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.defdex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.defdex.io/_mcp/server.

# Authentication and limits

Create and manage keys at [API keys](https://app.defdex.io/developer/keys).
Key management requires a signed-in account with verified email. Each key's full value
is displayed once; DefDex stores its hash. Use a separate named key for each integration.

## Authenticate requests

REST and MCP use an `Authorization` header:

```text
Authorization: Bearer YOUR_PRIVATE_KEY
```

The SDKs and CLI read `DEFDEX_API_KEY` from your environment. Store credentials in a
secret manager or private environment. Do not put keys in query strings, source control,
frontend bundles or diagnostic logs. HTTPS is required for remote SDK endpoints.

## Choose scopes

| Scope                  | Access                                                               |
| ---------------------- | -------------------------------------------------------------------- |
| `data:read`            | Discover collections, list/search published records and read details |
| `corrections:submit`   | Submit a proposed correction for human review                        |
| `corrections:read-own` | List/read your account's correction proposals and review notes       |

Keys default to `data:read`; opt into correction scopes when needed. No key permits
direct research edits. Account identity comes from the key; supplying someone else's
account ID cannot select their data. Usage is readable by any valid key for its account.

An account can have at most 10 active keys. To rotate, create a replacement, update
and verify the integration, then revoke the old key on the keys page. Revoked keys
cannot read data or call MCP tools.

## Account request limit

All keys belonging to one account share **60 admitted requests per rolling minute**.
A request to the usage endpoint also counts. Admitted errors and idempotent correction
replays count; usage counts do not imply charges. Website browsing is separate.

Valid MCP data tool calls enter the same REST admission path and ledger, without double
counting. Protocol discovery does not count as a data read. Using more keys does not
increase the account limit.

For request-rate 429 responses, wait for `Retry-After` before retrying. Correction
storage caps are separate and can return 429 without that header; see
[correction limits](/proposed-corrections).

## Inspect usage

Open [API usage](https://app.defdex.io/developer/usage) or call `GET /api/v1/usage`.
The response includes `days: 30`, usage grouped by day/endpoint/status (at most 1,000
groups), and `billing_active: false`. Paid billing is disabled. This endpoint is an
activity summary, not a remaining-quota or real-time billing quote.

Responses are `private, no-store`. Admitted requests include `X-Request-Id` for support.
See [errors and retries](/errors) for retry and troubleshooting behavior.