Authentication

All Orsa API requests require authentication via an API key.

API Key Format

Orsa API keys use the format:

orsa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Production
orsa_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Test/sandbox

Passing Your Key

Include your API key in the Authorization header using the Bearer scheme:

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

TypeScript SDK

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

Python SDK

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

Managing Keys

Create a Key

1. Go to orsa.dev/api-keys (opens in a new tab)
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.

Error Responses