Authentication and limits

Sending your key

Every call to /graphql and /mcp needs an API key. Send it as a bearer token:

Authorization: Bearer rdb_…

Clients that can only set a custom header can use X-Api-Key: rdb_… instead. Create, name and revoke keys on your account page. We store only a SHA-256 hash of each key, so a lost key can't be recovered; revoke it and create another.

The docs, /schema.graphql and /llms.txt are public and need no key.

Limits

• Limits apply to your account: all your keys share them.
• One GraphQL HTTP request counts as one request, however many fields it asks for. Over MCP, each tools/call counts as one; initialize, tools/list and reading the schema resource are free.
• Photo checks (identifyCard, identifyCards (one per card identified), assessCondition, checkAuthenticity, and their MCP, CLI and Studio equivalents) have their own daily allowance, because each runs a vision model. One counts only when it returns a result; a rejected photo or an outage costs nothing. viewer { visionRemaining } and raritydb whoami show what's left.
• The daily count resets at midnight UTC. Your account page shows today's usage and the last 30 days.
• Queries are also limited in size: depth 15, complexity 5,000, and at most 100 items per page.

Every successful response carries:

X-RateLimit-Limit: 1000        # your daily limit
X-RateLimit-Remaining: 987     # left today

Errors

A missing, wrong or revoked key gets 401:

{ "errors": [ { "message": "Send your API key as `Authorization: Bearer rdb_…` …", "extensions": { "code": "UNAUTHENTICATED" } } ] }

Going over a limit gets 429 with a Retry-After header (seconds) and one of these codes:

• RATE_LIMITED: more than 60 requests in a minute. Wait and retry.
• QUOTA_EXCEEDED: the day's requests are used up. Retry after midnight UTC.

See Errors, terms and attribution for GraphQL-level errors.

This page as Markdown: /docs/authentication.md