Authentication

Manage user authentication, access tokens, and secure sessions with the Account API.

Authentication Methods

Cerevox supports two authentication methods:

API Key (Recommended)

Best for: Server-side applications, scripts, automation

from cerevox import Hippo, Lexa

# Use API key directly
hippo = Hippo(api_key="your-api-key")
lexa = Lexa(api_key="your-api-key")

Get API key: cerevox.ai

OAuth Tokens

Best for: User-facing applications, mobile apps, web apps

from cerevox import Account

account = Account()

# Login to get tokens
auth = account.login(email, password)

# Use access token
hippo = Hippo(access_token=auth.access_token)

Use case: Multi-user applications

OAuth Authentication Flow

from cerevox import Account

account = Account()

# Login with email/password
auth_response = account.login(
    email="user@example.com",
    password="secure-password"
)

print(f"Access Token: {auth_response.access_token}")
print(f"Refresh Token: {auth_response.refresh_token}")
print(f"Expires In: {auth_response.expires_in} seconds")
print(f"Token Type: {auth_response.token_type}")

from cerevox import AsyncAccount

async with AsyncAccount() as account:
    auth = await account.login(
        email="user@example.com",
        password="password"
    )

    print(f"Access Token: {auth.access_token}")

Response fields:

access_token: Short-lived token for API requests (1 hour)
refresh_token: Long-lived token to get new access tokens (30 days)
expires_in: Seconds until access token expires
token_type: Token type (usually “Bearer”)

2. Use Access Token

from cerevox import Hippo, Lexa

# Use access token with any Cerevox API
hippo = Hippo(access_token=auth_response.access_token)
lexa = Lexa(access_token=auth_response.access_token)

# Make API calls
folder = hippo.create_folder("My Docs")
documents = lexa.parse(["doc.pdf"])

3. Refresh Token

Access tokens expire after 1 hour. Refresh before expiry:

# Refresh to get new access token
new_auth = account.refresh_token(
    refresh_token=auth_response.refresh_token
)

print(f"New Access Token: {new_auth.access_token}")
print(f"Expires In: {new_auth.expires_in} seconds")

new_auth = await account.refresh_token(
    refresh_token=auth_response.refresh_token
)

4. Revoke Token (Logout)

# Revoke token to log out
account.revoke_token(token=auth_response.access_token)

print("Logged out successfully")

await account.revoke_token(token=auth_response.access_token)

After revoking, the access token can no longer be used for API requests.

Complete Authentication Flow

from cerevox import Account, Hippo
import time

class AuthManager:
    def __init__(self):
        self.account = Account()
        self.auth_response = None

    def login(self, email, password):
        """Login and store tokens"""
        self.auth_response = self.account.login(email, password)

        # Calculate expiry time
        self.auth_response.expires_at = (
            time.time() + self.auth_response.expires_in
        )

        print(f"✅ Logged in as {email}")
        return self.auth_response

    def get_valid_token(self):
        """Get valid access token, refreshing if needed"""
        # Check if token expires within 5 minutes
        if time.time() > self.auth_response.expires_at - 300:
            print("🔄 Refreshing token...")

            self.auth_response = self.account.refresh_token(
                self.auth_response.refresh_token
            )

            self.auth_response.expires_at = (
                time.time() + self.auth_response.expires_in
            )

            print("✅ Token refreshed")

        return self.auth_response.access_token

    def logout(self):
        """Revoke token and log out"""
        self.account.revoke_token(self.auth_response.access_token)
        self.auth_response = None
        print("✅ Logged out")

# Usage
auth_manager = AuthManager()

# Login
auth_manager.login("user@example.com", "password")

# Use with Hippo
hippo = Hippo(access_token=auth_manager.get_valid_token())
folder = hippo.create_folder("My Docs")

# Token automatically refreshes when needed
time.sleep(3600)  # Wait 1 hour
hippo = Hippo(access_token=auth_manager.get_valid_token())  # Auto-refreshes

# Logout when done
auth_manager.logout()

Secure Token Storage

Never store tokens in:

Source code
Version control (git)
Client-side storage (localStorage, cookies without security)
Plain text files

Recommended: Environment Variables

import os

# Store tokens in environment variables
os.environ['CEREVOX_ACCESS_TOKEN'] = auth_response.access_token
os.environ['CEREVOX_REFRESH_TOKEN'] = auth_response.refresh_token

# Retrieve when needed
access_token = os.getenv('CEREVOX_ACCESS_TOKEN')

Recommended: Secure Keyring

import keyring

# Store tokens securely in system keyring
keyring.set_password("cerevox", "access_token", auth_response.access_token)
keyring.set_password("cerevox", "refresh_token", auth_response.refresh_token)

# Retrieve when needed
access_token = keyring.get_password("cerevox", "access_token")
refresh_token = keyring.get_password("cerevox", "refresh_token")

Server-Side Sessions

from flask import Flask, session

app = Flask(__name__)
app.secret_key = 'your-secret-key'  # Use secure random key

@app.route('/login', methods=['POST'])
def login():
    # Login
    auth = account.login(email, password)

    # Store in server-side session
    session['access_token'] = auth.access_token
    session['refresh_token'] = auth.refresh_token
    session['expires_at'] = time.time() + auth.expires_in

    return "Logged in"

@app.route('/api/data')
def get_data():
    # Use token from session
    access_token = session.get('access_token')

    hippo = Hippo(access_token=access_token)
    # ... use hippo ...

Error Handling

from cerevox import Account, AccountError

account = Account()

try:
    auth = account.login(email="user@example.com", password="wrong-password")

except AccountError as e:
    if "invalid credentials" in str(e).lower():
        print("Error: Invalid email or password")
    elif "account locked" in str(e).lower():
        print("Error: Account locked due to too many failed attempts")
    elif "not found" in str(e).lower():
        print("Error: Account not found")
    else:
        print(f"Error: {e}")

# Token expiry handling
try:
    hippo = Hippo(access_token=expired_token)
    folder = hippo.create_folder("Test")

except AccountError as e:
    if "token expired" in str(e).lower():
        # Refresh token
        new_auth = account.refresh_token(refresh_token)
        hippo = Hippo(access_token=new_auth.access_token)

        # Retry operation
        folder = hippo.create_folder("Test")

Token Lifecycle

User provides credentials → Receive access + refresh tokens

Use Access Token

Include access token in API requests (valid for 1 hour)

Refresh Token

Before expiry, use refresh token to get new access token

Logout

Revoke access token when user logs out

Multi-User Application Example

from cerevox import Account, Hippo
from flask import Flask, request, session, jsonify

app = Flask(__name__)
app.secret_key = 'secure-random-key'

account = Account()

@app.route('/auth/login', methods=['POST'])
def login():
    """User login endpoint"""
    data = request.json

    try:
        auth = account.login(
            email=data['email'],
            password=data['password']
        )

        # Store in session
        session['access_token'] = auth.access_token
        session['refresh_token'] = auth.refresh_token
        session['expires_at'] = time.time() + auth.expires_in

        return jsonify({'message': 'Logged in successfully'})

    except Exception as e:
        return jsonify({'error': str(e)}), 401

@app.route('/auth/logout', methods=['POST'])
def logout():
    """User logout endpoint"""
    try:
        # Revoke token
        account.revoke_token(session['access_token'])

        # Clear session
        session.clear()

        return jsonify({'message': 'Logged out successfully'})

    except Exception as e:
        return jsonify({'error': str(e)}), 400

def get_valid_token():
    """Helper to get valid access token"""
    # Check if token expires soon
    if time.time() > session.get('expires_at', 0) - 300:
        # Refresh token
        auth = account.refresh_token(session['refresh_token'])

        # Update session
        session['access_token'] = auth.access_token
        session['expires_at'] = time.time() + auth.expires_in

    return session['access_token']

@app.route('/api/folders', methods=['POST'])
def create_folder():
    """Protected endpoint - requires authentication"""
    try:
        # Get valid token
        access_token = get_valid_token()

        # Use with Hippo
        hippo = Hippo(access_token=access_token)
        folder = hippo.create_folder(request.json['name'])

        return jsonify({
            'id': folder.id,
            'name': folder.name
        })

    except Exception as e:
        return jsonify({'error': str(e)}), 400

if __name__ == '__main__':
    app.run()

Best Practices

Proactive Token Refresh

Refresh tokens before they expire:

# ✅ Good - Refresh 5 minutes before expiry
if time.time() > expires_at - 300:
    auth = account.refresh_token(refresh_token)

# ❌ Bad - Wait until token expires
try:
    hippo.create_folder("Test")
except:
    auth = account.refresh_token(refresh_token)

Prevents failed requests due to expiry

Secure Credential Handling

# ✅ Good
password = os.getenv('USER_PASSWORD')
access_token = keyring.get_password("cerevox", "token")

# ❌ Bad
password = "hardcoded-password"
access_token = "sk_live_abc123..."

Never hardcode credentials!

Implement Logout

Always provide logout functionality:

def logout():
    # Revoke token
    account.revoke_token(access_token)

    # Clear stored tokens
    session.clear()
    # or
    keyring.delete_password("cerevox", "access_token")

Prevents unauthorized access after user leaves

Handle Token Refresh Failures

try:
    auth = account.refresh_token(refresh_token)
except AccountError:
    # Refresh token expired or revoked
    # Force user to log in again
    redirect_to_login()

Gracefully handle expired refresh tokens

Security Checklist

Use HTTPS for all API requests
Never commit API keys or tokens to version control
Store tokens securely (keyring, encrypted storage)
Implement token refresh before expiry
Provide logout functionality
Handle authentication errors gracefully
Use environment variables for secrets
Implement rate limiting on login endpoint
Log authentication events for security monitoring

Getting Started

Hippo - RAG & Retrieval

Lexa - Document Parsing

Account Management

Examples

Guides

Use Cases

Company

Legal

Authentication

Authentication

Authentication Methods

API Key (Recommended)

OAuth Tokens

OAuth Authentication Flow

2. Use Access Token

3. Refresh Token

4. Revoke Token (Logout)

Complete Authentication Flow

Secure Token Storage

Recommended: Environment Variables

Recommended: Secure Keyring

Server-Side Sessions

Error Handling

Token Lifecycle

Multi-User Application Example

Best Practices

Security Checklist

Next Steps

Usage Tracking

Account Overview

​Authentication

​Authentication Methods

API Key (Recommended)

OAuth Tokens

​OAuth Authentication Flow

​1. Login

​2. Use Access Token

​3. Refresh Token

​4. Revoke Token (Logout)

​Complete Authentication Flow

​Secure Token Storage

​Recommended: Environment Variables

​Recommended: Secure Keyring

​Server-Side Sessions

​Error Handling

​Token Lifecycle

​Multi-User Application Example

​Best Practices

​Security Checklist

​Next Steps

Usage Tracking

Account Overview

Authentication

Authentication Methods

OAuth Authentication Flow

1. Login

2. Use Access Token

3. Refresh Token

4. Revoke Token (Logout)

Complete Authentication Flow

Secure Token Storage

Recommended: Environment Variables

Recommended: Secure Keyring

Server-Side Sessions

Error Handling

Token Lifecycle

Multi-User Application Example

Best Practices

Security Checklist

Next Steps