Authentication

All Orsa API requests require authentication via an API key.

API Key Format

Orsa API keys use the format:

or_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Production
or_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Test/sandbox

Passing Your Key

Two equivalent ways. The SDK uses x-api-key by default; the cURL examples in the API reference use Authorization: Bearer.

# Authorization header
curl -X GET "https://api.orsa.dev/v1/brand/retrieve?domain=example.com" \
  -H "Authorization: Bearer or_live_your_key_here"
 
# x-api-key header
curl -X GET "https://api.orsa.dev/v1/brand/retrieve?domain=example.com" \
  -H "x-api-key: or_live_your_key_here"

TypeScript SDK

import Orsa from '@orsa.dev/sdk';
 
const client = new Orsa({
  apiKey: process.env.ORSA_API_KEY!,  // Recommended: use environment variables
});

Python SDK

import os
from orsa import Orsa
 
client = Orsa(api_key=os.environ["ORSA_API_KEY"])

Managing Keys

Create a Key

1. Go to orsa.dev/dashboard/api-keys
2. Click Create Key
3. Give it a descriptive name (e.g., “Production”, “CI/CD”, “Development”)
4. Copy the key immediately — it’s only shown once

Revoke a Key

Click the trash icon next to any key in the dashboard. Revocation is immediate and irreversible. Any requests using that key will return 401 Unauthorized.

Key Scoping

Security Best Practices

• Never commit keys to version control. Use environment variables or secret managers.
• Use separate keys for development, staging, and production.
• Rotate keys periodically — create a new key, update your deployments, then revoke the old one.
• Monitor usage in the dashboard to detect unauthorized access.
• Server-side only. API keys are secrets — never ship one to the browser. Frameworks like Next.js Server Actions and Remix loaders keep keys safely server-side.

Error Responses

In the SDK these surface as OrsaAPIError with status and errorCode set. See Error Handling.