API Key Authentication
API keys are the recommended way to authenticate with the Orchata API. They’re perfect for:- Server-side applications
- CI/CD pipelines
- AI agents and MCP integrations
- Any programmatic access
Creating an API Key
1
Go to Settings
Navigate to API Keys in the Orchata dashboard.
2
Create API Key
Click Create API Key and enter a descriptive name.
3
Copy Your Key
Copy the API key immediately - you won’t see it again.
Using Your API Key
Include your API key in theOai-Api-Key header:
You can also use the
Authorization: Bearer your-api-key header if you prefer standard Bearer token auth.API Key Properties
| Property | Description |
|---|---|
id | Unique identifier |
name | Human-readable name for identification |
prefix | First few characters (e.g., abc...) for identification |
expiresAt | Optional expiration date |
permissions | Granular access control |
Tier-Specific Constraints
API key capabilities vary by pricing tier. Your tier determines how many keys you can create, expiration requirements, and permission options.| Constraint | Sandbox | Developer | Pro |
|---|---|---|---|
| Max API Keys | 1 | 10 | Unlimited |
| Expiry Required | Yes (30 days) | No | No |
| Max Expiry Days | 30 (enforced) | Unlimited | Unlimited |
| Rate Limiting | Required (max 100/day) | Optional | Optional |
| Custom Permissions | No | No | Yes |
- Only 1 API key allowed
- Expiry is mandatory and set to exactly 30 days
- Rate limiting cannot be disabled (max 100 requests per day)
- Up to 10 API keys
- Expiry is optional
- Rate limiting is configurable
- Standard permission levels only
- Unlimited API keys
- Expiry is optional
- Rate limiting is configurable
- Custom permission sets - Create fine-grained permission configurations beyond standard levels
Need more API keys or custom permissions? View plans to upgrade your tier.
Expiration
API keys can be set to expire after a specific date. This is useful for:- Temporary access for contractors
- Rotating keys on a schedule
- Time-limited integrations
Permissions
API keys can have granular permissions to limit their access. Permissions are organized by resource type.Available Permissions
Space Permissions
Space Permissions
| Permission | Description |
|---|---|
spaces:read | List and view spaces |
spaces:write | Create and update spaces |
spaces:delete | Archive/delete spaces |
Document Permissions
Document Permissions
| Permission | Description |
|---|---|
documents:read | List and view documents |
documents:write | Upload and update documents |
documents:delete | Delete documents |
Query Permissions
Query Permissions
| Permission | Description |
|---|---|
queries:read | Execute queries |
API Key Permissions
API Key Permissions
| Permission | Description |
|---|---|
apikeys:read | List API keys |
apikeys:write | Create API keys |
apikeys:delete | Delete API keys |
Principle of Least Privilege
Example: A read-only key for an AI agent:Session Authentication
The Orchata web dashboard uses session-based authentication. This is handled automatically when you log in. Session auth is also available for the MCP server when accessed through OAuth-enabled clients.Error Responses
Authentication errors return standard HTTP status codes:| Status | Error | Description |
|---|---|---|
401 | Unauthorized | Missing or invalid API key |
403 | Forbidden | Valid key but insufficient permissions |
Security Best Practices
Use Environment Variables
Never hardcode API keys in source code.
Rotate Regularly
Change API keys periodically, especially after team changes.
Limit Permissions
Grant only the permissions each key needs.
Set Expiration
Use expiring keys for temporary access.