Authentication

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:

curl https://enterprise.tavrn.ai/v2/cases \
  -H "Authorization: Bearer tavrn_sk_live_4nK8fR2mX9pQ..."

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

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

Managing API Keys

API keys are managed through your organization dashboard:

Navigate to your dashboard → Settings → API Keys
Click “Create API Key”
Select permission scopes
Copy and securely store the generated key (shown only once!)

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

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

# 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

{
  "error": {
    "code": "invalid_api_key",
    "message": "No API key provided"
  }
}

HTTP Status: 401 Unauthorized

Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid API key"
  }
}

HTTP Status: 401 Unauthorized

Insufficient Scope

{
  "error": {
    "code": "insufficient_scope",
    "message": "Required scope: retrievals:write"
  }
}

HTTP Status: 403 Forbidden

Get started

Retrieval reference

Case documents

Overview

API Key Format

Making Authenticated Requests

Permission Scopes

Managing API Keys

Security Best Practices

Never Expose Keys

Secure Storage

Key Rotation

Scope Restriction

Error Responses

Missing API Key

Invalid API Key

Insufficient Scope

Next Steps

​Overview

​API Key Format

​Making Authenticated Requests

​Permission Scopes

​Managing API Keys

​Security Best Practices

​Never Expose Keys

​Secure Storage

​Key Rotation

​Scope Restriction

​Error Responses

​Missing API Key

​Invalid API Key

​Insufficient Scope

​Next Steps

Overview

API Key Format

Making Authenticated Requests

Permission Scopes

Managing API Keys

Security Best Practices

Never Expose Keys

Secure Storage

Key Rotation

Scope Restriction

Error Responses

Missing API Key

Invalid API Key

Insufficient Scope

Next Steps