Authentication - Cerevox

Get your API key from cerevox.ai/lexa - it’s free to start.

All Authentication Methods

Environment Variable (Recommended)
Direct in Code
.env File
Configuration File

Best for: Production applications and general use

# Set your API key
export CEREVOX_API_KEY="your-api-key-here"

from cerevox import Lexa

# Client automatically reads from CEREVOX_API_KEY
client = Lexa()

# Test it works
documents = client.parse(b"Test authentication")
print("✅ Authenticated successfully!")

Most secure method - keeps keys out of your code

Best for: Quick testing and prototyping

from cerevox import Lexa

# Pass API key directly
client = Lexa(api_key="your-api-key-here")

# For async operations
from cerevox import AsyncLexa

async def main():
    async with AsyncLexa(api_key="your-api-key-here") as client:
        documents = await client.parse(["document.pdf"])

Don’t hardcode keys in production - use environment variables instead

Best for: Local development

.env

# Create .env file in your project root
CEREVOX_API_KEY=your-api-key-here

import os
from dotenv import load_dotenv
from cerevox import Lexa

# Load .env file
load_dotenv()

# Client reads from environment
client = Lexa()

# Install python-dotenv first
pip install python-dotenv

Best for: Complex applications

config.json

{
  "cerevox": {
    "api_key": "your-api-key-here",
    "timeout": 120,
    "max_retries": 3
  }
}

import json
from cerevox import Lexa

with open("config.json") as f:
    config = json.load(f)

client = Lexa(
    api_key=config["cerevox"]["api_key"],
    timeout=config["cerevox"]["timeout"],
    max_retries=config["cerevox"]["max_retries"]
)

Test Your Authentication

Copy and run this to verify your setup works:

from cerevox import Lexa, LexaError

def test_auth():
    try:
        client = Lexa()
        
        # Test with sample content
        documents = client.parse(b"Authentication test content")
        
        if documents:
            print("✅ Authentication successful!")
            print(f"📄 Parsed: {documents[0].content}")
            return True
        
    except LexaError as e:
        print(f"❌ API Error: {e.message}")
        if "authentication" in e.message.lower():
            print("💡 Check your API key at cerevox.ai/lexa")
        return False
    except Exception as e:
        print(f"❌ Error: {e}")
        return False

# Run the test
test_auth()

import os

def check_setup():
    # Check if API key exists
    api_key = os.getenv("CEREVOX_API_KEY")
    
    if not api_key:
        print("❌ CEREVOX_API_KEY not found")
        print("💡 Set it: export CEREVOX_API_KEY='your-key'")
        return False
    
    if len(api_key) < 10:
        print("❌ API key seems invalid (too short)")
        return False
        
    print(f"✅ API key found: {api_key[:8]}...")
    return True

check_setup()

import asyncio
from cerevox import AsyncLexa, LexaError

async def test_async_auth():
    try:
        async with AsyncLexa() as client:
            documents = await client.parse(b"Async test content")
            
            if documents:
                print("✅ Async authentication works!")
                return True
                
    except LexaError as e:
        print(f"❌ API Error: {e.message}")
        return False

asyncio.run(test_async_auth())

Direct API Usage

Using the REST API directly? Include your API key in the Authorization header:

curl -X POST "https://data.cerevox.ai/v0/parse" \
  -H "Authorization: Bearer your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "files": ["https://example.com/document.pdf"]  
  }'

import requests

headers = {
    "Authorization": "Bearer your-api-key-here",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://data.cerevox.ai/v0/parse",
    headers=headers,
    json={"files": ["document.pdf"]}
)

print(response.json())

const response = await fetch('https://data.cerevox.ai/v0/parse', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    files: ['document.pdf']
  })
});

const data = await response.json();
console.log(data);

Common Issues & Solutions

Invalid API Key

Error: Authentication failed or Invalid API keyQuick fixes:

# Check for extra spaces/quotes
import os
api_key = os.getenv('CEREVOX_API_KEY', '').strip()
print(f"Key length: {len(api_key)}")
print(f"First 8 chars: {api_key[:8]}")

# Get a fresh key from cerevox.ai/lexa if needed
client = Lexa(api_key=api_key)

API Key Not Found

Error: No API key providedQuick fixes:

# Check if it's set
echo $CEREVOX_API_KEY

# Set it (Linux/Mac)
export CEREVOX_API_KEY="your-key"

# Set it (Windows)
set CEREVOX_API_KEY=your-key

# Verify in Python
import os; print(os.getenv('CEREVOX_API_KEY'))

Connection Issues

Error: Connection timeout or network errorsQuick fixes:

# Increase timeout
client = Lexa(timeout=180.0)

# Check proxy settings if needed
import os
os.environ['HTTPS_PROXY'] = 'http://your-proxy:port'

# Test with smaller content first
client.parse(b"small test")

Permission Denied

Error: Insufficient permissions or Access deniedQuick fixes:

Check your account status at cerevox.ai/lexa
Verify your plan includes the features you’re using
Check if you’ve hit rate limits (wait a minute and retry)
Contact support@cerevox.ai if issues persist

Security Best Practices

Use Environment Variables

Keep API keys out of your code with environment variables

Rotate Keys Regularly

Generate new keys every 90 days for enhanced security

Monitor Usage

Watch for unusual API usage patterns in your dashboard

Least Privilege

Use API keys with only the permissions you need

Production Setup Examples

Docker
GitHub Actions
Kubernetes

FROM python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .

# API key provided at runtime, not in image
CMD ["python", "app.py"]

# Run with API key
docker run -e CEREVOX_API_KEY="your-key" my-lexa-app

name: Test Lexa
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.9'
      - run: pip install cerevox
      - name: Test Lexa API
        env:
          CEREVOX_API_KEY: ${{ secrets.CEREVOX_API_KEY }}
        run: python test_lexa.py

apiVersion: v1
kind: Secret
metadata:
  name: cerevox-secret
type: Opaque
stringData:
  api-key: your-api-key-here
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: lexa-app
spec:
  template:
    spec:
      containers:
      - name: app
        image: my-lexa-app
        env:
        - name: CEREVOX_API_KEY
          valueFrom:
            secretKeyRef:
              name: cerevox-secret
              key: api-key

Ready to parse? Head to the quickstart guide to make your first API call, or check out code examples.

​All Authentication Methods

​Test Your Authentication

​Direct API Usage

​Common Issues & Solutions

​Security Best Practices

Use Environment Variables

Rotate Keys Regularly

Monitor Usage

Least Privilege

​Production Setup Examples

All Authentication Methods

Test Your Authentication

Direct API Usage

Common Issues & Solutions

Security Best Practices

Production Setup Examples