Authentication

Which credential each endpoint accepts, and which header carries it.

dev · https://api.dev.oprag.ai

Four credentials

Credential	Header	Used from	With no Origin header	With one
Integration key	`X-Oprag-Key`	Server	Allowed. Server-to-server callers (curl, your backend) send no Origin.	The Origin must be on the project's allowlist. An empty allowlist rejects every browser Origin.
Embed key	`X-Oprag-Key`	Browser	403. Embed keys require a browser Origin header — there is no server-side fallback.	The Origin must be on the project's allowlist. An empty allowlist rejects all.
Share token	`X-Oprag-Share-Token`	Either	Allowed. Share links are opened directly and carry their own signed token.	Not origin-restricted; the token itself is the credential.
Cognito JWT	`Authorization: Bearer <JWT>`	Browser	Allowed. Dashboard routes are authorised by the token, not the Origin.	CORS is handled by API Gateway; the project allowlist does not apply.

Header precedence

X-Oprag-Key is read first when present.
Otherwise the key is taken from Authorization: Bearer <key>.
Sending both is not an error — the dedicated header wins.

Shell

# Preferred
curl 'https://api.dev.oprag.ai/v1/chat' -H 'X-Oprag-Key: sk_live_...'

# Equivalent
curl 'https://api.dev.oprag.ai/v1/chat' -H 'Authorization: Bearer sk_live_...'

Public chat takes three of them

POST /v1/chat accepts an integration key, an embed key, or a share token — not integration keys alone. Which one you send determines the origin rules that apply, which is the part worth getting right.

Shell

# Server-to-server: integration key, no Origin needed.
curl -X POST 'https://api.dev.oprag.ai/v1/chat' \
  -H 'X-Oprag-Key: sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{"question":"What is your refund policy?"}'

# Browser: embed key, and the Origin must be allowlisted.
curl -X POST 'https://api.dev.oprag.ai/v1/chat' \
  -H 'X-Oprag-Key: embed_live_...' \
  -H 'Origin: https://your-site.example' \
  -H 'Content-Type: application/json' \
  -d '{"question":"What is your refund policy?"}'

# Shared conversation link: a signed share token.
curl -X POST 'https://api.dev.oprag.ai/v1/chat' \
  -H 'X-Oprag-Share-Token: <token>' \
  -H 'Content-Type: application/json' \
  -d '{"question":"What is your refund policy?"}'

Dashboard endpoints

Everything under the dashboard API takes a Cognito JWT as Authorization: Bearer <JWT>, and enforces a role on top. Sign-in itself is OAuth & sign-in.

Ready to ship?

Get started free