Authentication

All Orchata API endpoints require authentication. We support two authentication methods: API Keys for programmatic access and Session Auth for the web dashboard.

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

Go to Settings

Navigate to API Keys in the Orchata dashboard.

Create API Key

Click Create API Key and enter a descriptive name.

Copy Your Key

Copy the API key immediately - you won’t see it again.

API keys are shown only once. Store them securely in environment variables or a secrets manager.

Using Your API Key

Include your API key in the Oai-Api-Key header:

curl -X GET https://api.orchata.ai/spaces \
  -H "Oai-Api-Key: your-api-key"

const response = await fetch('https://api.orchata.ai/spaces', {
  headers: {
    'Oai-Api-Key': process.env.ORCHATA_API_KEY
  }
});

import requests

response = requests.get(
    'https://api.orchata.ai/spaces',
    headers={'Oai-Api-Key': os.environ['ORCHATA_API_KEY']}
)

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

Sandbox Tier:

Only 1 API key allowed
Expiry is mandatory and set to exactly 30 days
Rate limiting cannot be disabled (max 100 requests per day)

Developer Tier:

Up to 10 API keys
Expiry is optional
Rate limiting is configurable
Standard permission levels only

Pro Tier:

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

{
  "name": "CI/CD Pipeline",
  "expiresAt": "2024-12-31T23:59:59Z"
}

For production applications, consider rotating API keys periodically as a security best practice.

Permissions

API keys can have granular permissions to limit their access. Permissions are organized by resource type.

Available Permissions

Space Permissions

Permission	Description
`spaces:read`	List and view spaces
`spaces:write`	Create and update spaces
`spaces:delete`	Archive/delete spaces

Document Permissions

Permission	Description
`documents:read`	List and view documents
`documents:write`	Upload and update documents
`documents:delete`	Delete documents

Query Permissions

Permission	Description
`queries:read`	Execute queries

API Key Permissions

Permission	Description
`apikeys:read`	List API keys
`apikeys:write`	Create API keys
`apikeys:delete`	Delete API keys

Principle of Least Privilege

Always grant the minimum permissions required. An API key for querying doesn’t need write access.

Example: A read-only key for an AI agent:

{
  "name": "AI Agent - Read Only",
  "permissions": ["spaces:read", "documents:read", "queries:read"]
}

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.

Organization Roles and Permissions

When using session authentication, your role within an organization determines what actions you can perform:

Action	Member	Admin	Owner
Spaces (create, update, delete)	✅ Create, ✅ Update, ❌ Delete	✅ Create, ✅ Update, ✅ Delete	✅ Create, ✅ Update, ✅ Delete
Organization Settings (name, billing)	❌ Name, ❌ Billing	✅ Name, ❌ Billing	✅ Name, ✅ Billing

Key Points:

Members can create and update spaces but cannot delete them
Admins have full space management access but cannot access billing settings
Owners have full access to all organization features including billing

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

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

{
  "error": "Forbidden",
  "message": "API key does not have 'documents:write' permission"
}

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.

Next Steps

MCP Server

Connect AI assistants to Orchata.

API Reference

Explore all available endpoints.

Getting Started

MCP Server

AI Tool Setup

CLI

TypeScript SDK

API Key Authentication

Creating an API Key

Using Your API Key

API Key Properties

Tier-Specific Constraints

Expiration

Permissions

Available Permissions

Principle of Least Privilege

Session Authentication

Organization Roles and Permissions

Error Responses

Security Best Practices

Use Environment Variables

Rotate Regularly

Limit Permissions

Set Expiration

Next Steps

MCP Server

API Reference

​API Key Authentication

​Creating an API Key

​Using Your API Key

​API Key Properties

​Tier-Specific Constraints

​Expiration

​Permissions

​Available Permissions

​Principle of Least Privilege

​Session Authentication

​Organization Roles and Permissions

​Error Responses

​Security Best Practices

Use Environment Variables

Rotate Regularly

Limit Permissions

Set Expiration

​Next Steps

MCP Server

API Reference

API Key Authentication

Creating an API Key

Using Your API Key

API Key Properties

Tier-Specific Constraints

Expiration

Permissions

Available Permissions

Principle of Least Privilege

Session Authentication

Organization Roles and Permissions

Error Responses

Security Best Practices

Next Steps