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

# Authentication

> API key authentication for Enterprise API v2

## Overview

The Enterprise API v2 uses API key authentication. All requests must include a valid API key in the `Authorization` header using the Bearer token format.

## API Key Format

API keys are prefixed strings:

* **Live keys**: `tavrn_sk_live_...`

## Making Authenticated Requests

Include your API key in every request:

```bash theme={null}
curl https://enterprise.tavrn.ai/v2/cases \
  -H "Authorization: Bearer tavrn_sk_live_4nK8fR2mX9pQ..."
```

```javascript theme={null}
// Node.js
const response = await fetch('https://enterprise.tavrn.ai/v2/cases', {
  headers: {
    'Authorization': 'Bearer tavrn_sk_live_4nK8fR2mX9pQ...'
  }
});
```

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

headers = {
    'Authorization': 'Bearer tavrn_sk_live_4nK8fR2mX9pQ...'
}

response = requests.get('https://enterprise.tavrn.ai/v2/cases', headers=headers)
```

## Permission Scopes

Each API key is created with specific permission scopes that control access to resources:

| Scope | Description |
| - | - |
| `cases:read` | Read case information |
| `cases:write` | Create and update cases |
| `documents:read` | Read case documents |
| `documents:write` | Upload and manage documents |
| `retrievals:read` | Search facilities and read retrieval requests |
| `retrievals:write` | Create and manage retrieval requests |
| `requestors:read` | List and read your organization's retrieval profiles |
| `requestors:write` | Create and update retrieval profiles and upload their documents |
| `webhooks:read` | List and get webhooks |
| `webhooks:write` | Create, update, delete, and test webhooks |

Use an API key with `retrievals:write` to create retrievals. An inline `requestor` also
requires `requestors:write`, and an inline `case` also requires `cases:write`.
See [Select a Requestor](/guides/v2/retrieval-guide#select-a-requestor).

## Managing API Keys

API keys are managed through your organization dashboard:

1. Navigate to your dashboard → Settings → API Keys
2. Click "Create API Key"
3. Select permission scopes
4. Copy and securely store the generated key (shown only once!)

<Warning>
  API keys are shown only once during creation. Store them securely - they cannot be retrieved later.
</Warning>

## Security Best Practices

### Never Expose Keys

* Never commit API keys to version control
* Never include keys in client-side code
* Use environment variables for key storage

### Secure Storage

```bash theme={null}
# Good: Environment variables
export TAVRN_API_KEY="tavrn_sk_live_..."

# Bad: Hard-coded in source
api_key = "tavrn_sk_live_..."  # Never do this!
```

### Key Rotation

* Rotate keys periodically (recommendation: every 90 days)
* Rotate immediately if a key is compromised
* Test new keys before deactivating old ones

### Scope Restriction

* Use the minimum required scopes for each key
* Create separate keys for different integrations
* Use `read` scopes where `write` isn't needed

## Error Responses

### Missing API Key

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "No API key provided"
  }
}
```

**HTTP Status**: 401 Unauthorized

### Invalid API Key

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}
```

**HTTP Status**: 401 Unauthorized

### Insufficient Scope

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "Required scope: retrievals:write"
  }
}
```

**HTTP Status**: 403 Forbidden

## Next Steps

* [Create your first case](/api-reference/v2/endpoint/cases/create-case)
* [Upload documents](/guides/v2/document-upload-guide)
* [Set up webhooks](/guides/v2/webhooks)