Authentication and limits

Create and manage keys at API 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:

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.

Inspect usage

Open API 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 for retry and troubleshooting behavior.