> ## Documentation Index
> Fetch the complete documentation index at: https://orchata.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with the Orchata API

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

<Steps>
  <Step title="Go to Settings">
    Navigate to **API Keys** in the [Orchata dashboard](https://app.orchata.ai).
  </Step>

  <Step title="Create API Key">
    Click **Create API Key** and enter a descriptive name.
  </Step>

  <Step title="Copy Your Key">
    Copy the API key immediately - you won't see it again.

    <Warning>
      API keys are shown only once. Store them securely in environment variables or a secrets manager.
    </Warning>
  </Step>
</Steps>

### Using Your API Key

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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://api.orchata.ai/spaces \
    -H "Oai-Api-Key: your-api-key"
  ```

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

  ```python Python theme={null}
  import requests

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

<Note>
  You can also use the `Authorization: Bearer your-api-key` header if you prefer standard Bearer token auth.
</Note>

### 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

<Info>
  Need more API keys or custom permissions? [View plans](/getting-started/plans) to upgrade your tier.
</Info>

### 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

```json theme={null}
{
  "name": "CI/CD Pipeline",
  "expiresAt": "2024-12-31T23:59:59Z"
}
```

<Tip>
  For production applications, consider rotating API keys periodically as a security best practice.
</Tip>

## Permissions

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

### Available Permissions

<AccordionGroup>
  <Accordion title="Space Permissions">
    | Permission      | Description              |
    | --------------- | ------------------------ |
    | `spaces:read`   | List and view spaces     |
    | `spaces:write`  | Create and update spaces |
    | `spaces:delete` | Archive/delete spaces    |
  </Accordion>

  <Accordion title="Document Permissions">
    | Permission         | Description                 |
    | ------------------ | --------------------------- |
    | `documents:read`   | List and view documents     |
    | `documents:write`  | Upload and update documents |
    | `documents:delete` | Delete documents            |
  </Accordion>

  <Accordion title="Query Permissions">
    | Permission     | Description     |
    | -------------- | --------------- |
    | `queries:read` | Execute queries |
  </Accordion>

  <Accordion title="API Key Permissions">
    | Permission       | Description     |
    | ---------------- | --------------- |
    | `apikeys:read`   | List API keys   |
    | `apikeys:write`  | Create API keys |
    | `apikeys:delete` | Delete API keys |
  </Accordion>
</AccordionGroup>

### Principle of Least Privilege

<Warning>
  Always grant the minimum permissions required. An API key for querying doesn't need write access.
</Warning>

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

```json theme={null}
{
  "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 |

<ResponseExample>
  ```json 401 Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 403 Forbidden theme={null}
  {
    "error": "Forbidden",
    "message": "API key does not have 'documents:write' permission"
  }
  ```
</ResponseExample>

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Use Environment Variables" icon="lock">
    Never hardcode API keys in source code.
  </Card>

  <Card title="Rotate Regularly" icon="arrows-rotate">
    Change API keys periodically, especially after team changes.
  </Card>

  <Card title="Limit Permissions" icon="shield-halved">
    Grant only the permissions each key needs.
  </Card>

  <Card title="Set Expiration" icon="clock">
    Use expiring keys for temporary access.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Server" icon="plug" href="/mcp/overview">
    Connect AI assistants to Orchata.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore all available endpoints.
  </Card>
</CardGroup>