Authentication

API Keys

Include your API key in the Authorization header as a Bearer token:

curl -X POST https://api.open-ocr.com/v1/ocr \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-ocr-your-api-key" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "engine": "mistral-mistral-ocr-4-1",
    "input": {
      "type": "url",
      "url": "https://example.com/document.png"
    }
  }'

Getting Your API Key

1. Sign up at open-ocr.com/signup — you get $1.00 in free credits immediately.
2. Go to your Dashboard → API Keys.
3. Click Create API Key, give it a name (e.g., "Production").
4. Copy the key — it starts with sk-ocr-. You will only see the full key once.

Key Security

API keys are stored as SHA-256 hashes — we never store your raw key. Best practices:

• Never expose keys in client-side code — use a backend proxy.
• Use environment variables — don't hardcode keys in source.
• Separate keys per environment — one for dev, one for production.
• Set usage limits — cap spending per key from the dashboard.
• Rotate regularly — revoke old keys and generate new ones.

# Store your key in environment variables
export OPENOCR_API_KEY="sk-ocr-your-api-key"

# Use it in your application
curl -H "Authorization: Bearer $OPENOCR_API_KEY" \
  https://api.open-ocr.com/v1/engines

HTTP Client Configuration

import os
import requests

response = requests.get(
    "https://api.open-ocr.com/v1/engines",
    headers={"Authorization": f"Bearer {os.environ['OPENOCR_API_KEY']}"},
)
response.raise_for_status()

// Node.js 18+
const response = await fetch("https://api.open-ocr.com/v1/engines", {
  headers: { Authorization: `Bearer ${process.env.OPENOCR_API_KEY}` },
});
if (!response.ok) throw new Error(`HTTP ${response.status}`);

Official OpenOCR SDKs are coming soon. For now, call the REST API with your preferred HTTP client.

Session Authentication

The Playground uses session-based authentication via Supabase JWT tokens. When logged in, your browser sends a JWT access token that the router validates against Supabase's JWKS endpoint (ES256). Credits are charged directly to your account balance.

For programmatic access, always use API keys. Session tokens are for the web playground only.

Rate Limits

All authenticated requests are rate-limited to 60 requests per minute per API key. Exceeding this limit returns 429 Too Many Requests with a Retry-After header.

# Rate limit headers on every response:
# X-RateLimit-Limit: 60
# X-RateLimit-Remaining: 59
# X-RateLimit-Reset: 1709856000

Authentication Errors

If authentication fails, you'll receive a 401 response:

{
  "error": {
    "code": "authentication_error",
    "message": "Invalid API key"
  }
}

Common causes: missing Bearer prefix, revoked key, or typo in the key string. See the Error Codes page for the full reference.