Authentication

Every request carries a bearer credential. There are two kinds, and each endpoint accepts specific ones.

API keys (programmatic)

API keys are for server-to-server access. Create one in the dashboard under API keys; the plaintext value (prefixed rag_live_) is shown exactly once. Send it as a bearer token:

curl 'https://rag.lucasfurtado.xyz/api/v1/collections' \
  -H 'Authorization: Bearer rag_live_YOUR_KEY'

An X-API-Key header is also accepted:

curl 'https://rag.lucasfurtado.xyz/api/v1/collections' \
  -H 'X-API-Key: rag_live_YOUR_KEY'

API keys can read and write collections, documents, and run queries. They are rate-limited per key (see rate limits) and cannot manage keys or read analytics.

Sessions (dashboard)

The dashboard authenticates with a Clerk session JWT, sent the same way (Authorization: Bearer <jwt>). Sessions are the only credential accepted by the dashboard-only endpoints — API-key management (/v1/api-keys) and analytics (/v1/analytics/*). Presenting an API key there returns 401.

Which credential does an endpoint accept?

Every operation in the reference is labeled with the schemes it accepts (API key, Session, or both), and the OpenAPI spec marks each with ApiKeyAuth and/or SessionAuth security requirements.

What happens on 401

A missing, malformed, expired, or revoked credential returns 401 with the standard error body. A revoked API key stops working immediately.

{ "error": "Invalid or expired credentials" }