Authentication Reference

Note

Complete reference for HoneyHive authentication methods and security

This document provides detailed specifications for authenticating with HoneyHive APIs and configuring security settings.

HoneyHive uses API keys for authentication across all SDK and API interactions. This reference covers all authentication methods, security best practices, and troubleshooting.

API Key Authentication

Basic Authentication

API Key Format:

All HoneyHive API keys follow this format: - Prefix: hh_ - Length: 32+ characters after prefix - Characters: Alphanumeric (a-z, A-Z, 0-9) - Example: hh_1234567890abcdef1234567890abcdef

Obtaining API Keys:

  1. HoneyHive Dashboard: - Navigate to Settings → API Keys - Click “Generate New API Key” - Copy and securely store the key - API keys are only shown once

  2. Team Management: - Team admins can generate keys for team members - Different permission levels available - Keys can be scoped to specific projects

API Key Permissions:

API Key Permission Levels

Level

Capabilities

Use Cases

Read Only

View projects, sessions, events

Monitoring, reporting, analysis

Read/Write

All read operations + create/update data

Application integration, data ingestion

Admin

All operations + manage projects/settings

Full control, configuration management

Authentication Methods

Environment Variable

Primary Method (Recommended):

# Set environment variable
export HH_API_KEY="hh_your_api_key_here"

Benefits: - Secure (not in code) - Environment-specific - Easy rotation - CI/CD friendly

Python Usage:

import os
from honeyhive import HoneyHiveTracer

# Automatically uses HH_API_KEY environment variable
tracer = HoneyHiveTracer.init(
    project="your-project"  # Or set HH_PROJECT environment variable
    # api_key not needed - loaded from HH_API_KEY environment variable
)

Direct Parameter

For Testing/Development:

from honeyhive import HoneyHiveTracer

# Direct API key parameter
tracer = HoneyHiveTracer.init(
    api_key="hh_your_api_key_here",  # Or set HH_API_KEY environment variable
    project="your-project"           # Or set HH_PROJECT environment variable
)

Use Cases: - Unit testing with mock keys - Development environments - Quick prototyping

Security Warning: Never commit API keys directly in code

Configuration File

YAML Configuration:

# honeyhive.yaml
api_key: "hh_your_api_key_here"
project: "my-project"

JSON Configuration:

{
  "api_key": "hh_your_api_key_here",
  "project": "my-project"
}

Loading Configuration:

from honeyhive import HoneyHiveTracer

# Load from config file
tracer = HoneyHiveTracer.init(config_file="honeyhive.yaml")

CLI Authentication

Login Command:

# Interactive login
honeyhive auth login --api-key hh_your_api_key_here

# Save credentials
honeyhive auth login --api-key hh_your_key --save

Check Authentication:

# Verify current authentication
honeyhive auth whoami

# Output:
# Authenticated as: user@example.com
# Organization: My Company
# Permissions: Read/Write

Logout:

# Logout current user
honeyhive auth logout

# Remove all stored credentials
honeyhive auth logout --all

Authentication Precedence

The SDK resolves authentication in this order (highest to lowest precedence):

  1. Direct Parameter: api_key parameter in function calls

  2. Environment Variable: HH_API_KEY environment variable

  3. Configuration File: api_key in config file

  4. CLI Stored Credentials: Credentials saved via honeyhive auth login

Example:

# This takes precedence over all other methods
tracer = HoneyHiveTracer.init(
    api_key="hh_direct_key",  # Highest precedence (or set HH_API_KEY environment variable)
    project="your-project"    # Or set HH_PROJECT environment variable
)

# This takes precedence over config file and CLI
export HH_API_KEY="hh_env_key"

Security Best Practices

API Key Management

Do’s:

✅ Use Environment Variables:

# Production deployment
export HH_API_KEY="hh_prod_key_here"

✅ Rotate Keys Regularly:

# Generate new key, update environment, revoke old key
honeyhive auth login --api-key hh_new_key_here

✅ Use Different Keys per Environment:

# Development
export HH_API_KEY="hh_dev_key_here"

# Staging
export HH_API_KEY="hh_staging_key_here"

# Production
export HH_API_KEY="hh_prod_key_here"

✅ Scope Keys Appropriately:

# Use read-only keys for monitoring
monitoring_tracer = HoneyHiveTracer.init(
    api_key="hh_readonly_key_here",  # Or set HH_API_KEY environment variable
    project="your-project"           # Or set HH_PROJECT environment variable
)

Don’ts:

❌ Never Commit Keys to Code:

# DON'T DO THIS
tracer = HoneyHiveTracer.init(
    api_key="hh_1234567890abcdef...",  # Never hardcode! Use HH_API_KEY environment variable
    project="your-project"             # Or set HH_PROJECT environment variable
)

❌ Don’t Share Keys: - Each developer should have their own key - Use service accounts for automated systems - Revoke keys when team members leave

❌ Don’t Log Keys:

import logging

# DON'T DO THIS
logging.info(f"Using API key: {api_key}")  # Never log keys!

# DO THIS INSTEAD
logging.info(f"Using API key: {api_key[:8]}***")  # Masked logging

Storage Security

Secure Storage Options:

  1. Environment Variables:

    # In .bashrc or .zshrc (for development)
export HH_API_KEY="hh_your_key_here"

    # In Kubernetes secrets
apiVersion: v1
kind: Secret
metadata:
  name: honeyhive-secret
data:
  api-key: aGhfeW91cl9rZXlfaGVyZQ==  # base64 encoded

  2. Cloud Secret Managers:

    # AWS Secrets Manager
import boto3

def get_honeyhive_key():
    client = boto3.client('secretsmanager')
    response = client.get_secret_value(SecretId='honeyhive-api-key')
    return response['SecretString']

    # Azure Key Vault
from azure.keyvault.secrets import SecretClient

def get_honeyhive_key():
    client = SecretClient(vault_url="https://vault.vault.azure.net/",
                         credential=credential)
    secret = client.get_secret("honeyhive-api-key")
    return secret.value

  3. Configuration Management:

    # Using python-decouple
from decouple import config

api_key = config('HH_API_KEY')
tracer = HoneyHiveTracer.init(
    api_key=api_key,         # Or set HH_API_KEY environment variable
    project="your-project"   # Or set HH_PROJECT environment variable
)

Access Control

Network Security:

# Restrict API access by IP (if available)
allowed_ips:
  - "192.168.1.0/24"    # Internal network
  - "10.0.0.0/8"        # VPN range
  - "203.0.113.10"      # Specific server

Rate Limiting:

# SDK handles rate limiting automatically
tracer = HoneyHiveTracer.init(
    api_key="hh_your_key",       # Or set HH_API_KEY environment variable
    project="your-project",      # Or set HH_PROJECT environment variable
    # Rate limiting is automatic
)

Environment-Specific Authentication

Development Environment

# .env.development
HH_API_KEY=hh_dev_1234567890abcdef
HH_BASE_URL=https://api-dev.honeyhive.ai
HH_TEST_MODE=false
HH_DEBUG=true

# Load development environment
from dotenv import load_dotenv
load_dotenv('.env.development')

from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(
    project="your-project"  # Or set HH_PROJECT environment variable
)  # Uses HH_API_KEY from .env.development

Testing Environment

# .env.test
HH_API_KEY=hh_test_1234567890abcdef
HH_BASE_URL=https://api-test.honeyhive.ai
HH_TEST_MODE=true
HH_DEBUG=false

# Testing with mock authentication
import pytest
from unittest.mock import patch

@patch.dict('os.environ', {'HH_API_KEY': 'hh_mock_key'})
def test_honeyhive_integration():
    from honeyhive import HoneyHiveTracer
    tracer = HoneyHiveTracer.init(
        project="your-project",  # Or set HH_PROJECT environment variable
        test_mode=True            # No real API calls (or set HH_TEST_MODE=true)
    )
    # Test your code here

Production Environment

# production.yaml (deployed securely)
api_key: "${HH_API_KEY}"  # Environment variable substitution
base_url: "https://api.honeyhive.ai"
project: "my-app-prod"
test_mode: false
debug: false

# Security settings
verify_ssl: true
timeout: 30.0

# Production deployment
export HH_API_KEY="hh_prod_secure_key_here"

# Start application
python app.py

CI/CD Authentication

GitHub Actions

# .github/workflows/test.yml
name: Test HoneyHive Integration

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v4
      with:
        python-version: '3.11'

    - name: Install dependencies
      run: |
        pip install honeyhive pytest

    - name: Run tests
      env:
        HH_API_KEY: ${{ secrets.HH_TEST_API_KEY }}
        HH_TEST_MODE: "true"
      run: |
        pytest tests/

Setting GitHub Secrets: 1. Repository Settings → Secrets and variables → Actions 2. New repository secret: HH_TEST_API_KEY 3. Value: Your test API key

GitLab CI

# .gitlab-ci.yml
test:
  image: python:3.11
  variables:
    HH_TEST_MODE: "true"
  script:
    - pip install honeyhive pytest
    - pytest tests/
  only:
    - merge_requests
    - main

Setting GitLab Variables: 1. Project Settings → CI/CD → Variables 2. Add variable: HH_TEST_API_KEY 3. Make it protected and masked

Jenkins

// Jenkinsfile
pipeline {
    agent any

    environment {
        HH_API_KEY = credentials('honeyhive-test-api-key')
        HH_TEST_MODE = 'true'
    }

    stages {
        stage('Test') {
            steps {
                sh '''
                    pip install honeyhive pytest
                    pytest tests/
                '''
            }
        }
    }
}

Setting Jenkins Credentials: 1. Manage Jenkins → Manage Credentials 2. Add Secret Text credential 3. ID: honeyhive-test-api-key

Docker Authentication

Dockerfile with Build Args:

FROM python:3.11

# Use build arg for API key (not recommended for production)
ARG HH_API_KEY
ENV HH_API_KEY=${HH_API_KEY}

# Install application
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
CMD ["python", "app.py"]

Build and Run:

# Build (not recommended - API key in build context)
docker build --build-arg HH_API_KEY=hh_your_key -t myapp .

# Better: Pass at runtime
docker run -e HH_API_KEY=hh_your_key myapp

Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  app:
    build: .
    environment:
      - HH_API_KEY=${HH_API_KEY}
    env_file:
      - .env.production

Docker Secrets (Docker Swarm):

# docker-compose.yml (with secrets)
version: '3.8'

services:
  app:
    image: myapp
    secrets:
      - honeyhive_api_key
    environment:
      - HH_API_KEY_FILE=/run/secrets/honeyhive_api_key

secrets:
  honeyhive_api_key:
    external: true

Kubernetes Authentication

Using Secrets:

# honeyhive-secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: honeyhive-secret
type: Opaque
data:
  api-key: aGhfeW91cl9rZXlfaGVyZQ==  # base64 encoded

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: app
        image: myapp:latest
        env:
        - name: HH_API_KEY
          valueFrom:
            secretKeyRef:
              name: honeyhive-secret
              key: api-key

Create Secret:

# Create secret from command line
kubectl create secret generic honeyhive-secret \
  --from-literal=api-key=hh_your_api_key_here

Using External Secrets Operator:

# external-secret.yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: honeyhive-secret
spec:
  refreshInterval: 15s
  secretStoreRef:
    name: aws-secrets-manager
    kind: SecretStore
  target:
    name: honeyhive-secret
  data:
  - secretKey: api-key
    remoteRef:
      key: honeyhive-api-key

Troubleshooting Authentication

Common Issues

Invalid API Key:

# Error: 401 Unauthorized
# Causes:
# 1. Wrong API key
# 2. Expired API key
# 3. API key not set

# Debug:
import os
print(f"API Key set: {'HH_API_KEY' in os.environ}")
print(f"API Key preview: {os.environ.get('HH_API_KEY', 'NOT_SET')[:8]}***")

Permission Denied:

# Error: 403 Forbidden
# Causes:
# 1. Insufficient permissions
# 2. Project access denied
# 3. Feature not enabled

# Check permissions:
honeyhive auth whoami

Network Issues:

# Error: Connection timeout
# Causes:
# 1. Network connectivity
# 2. Firewall blocking
# 3. SSL/TLS issues

# Debug:
import requests
response = requests.get("https://api.honeyhive.ai/api/v1/health")
print(f"API accessible: {response.status_code == 200}")

Configuration Issues:

# Debug configuration loading
from honeyhive.utils.config import get_config

config = get_config()
print(f"Configuration: {config}")
print(f"API Key source: {config.get('api_key_source', 'unknown')}")

Debugging Tools

CLI Debugging:

# Check authentication
honeyhive auth whoami --verbose

# Test API connectivity
honeyhive project list --debug

# Validate configuration
honeyhive config list

Python Debugging:

import logging
logging.basicConfig(level=logging.DEBUG)

from honeyhive import HoneyHiveTracer

# Enable debug mode
tracer = HoneyHiveTracer.init(
    api_key="hh_your_key",       # Or set HH_API_KEY environment variable
    project="your-project",      # Or set HH_PROJECT environment variable
    debug=True                   # Enables debug logging (or set HH_DEBUG_MODE=true)
)

Authentication Test Script:

#!/usr/bin/env python3
"""Test HoneyHive authentication"""

import os
import sys
from honeyhive import HoneyHive

def test_auth():
    """Test authentication and basic API access"""
    api_key = os.getenv('HH_API_KEY')

    if not api_key:
        print("❌ HH_API_KEY environment variable not set")
        return False

    if not api_key.startswith('hh_'):
        print("❌ API key format invalid (must start with 'hh_')")
        return False

    print(f"✅ API key format valid: {api_key[:8]}***")

    try:
        client = HoneyHive(api_key=api_key)
        projects = client.projects.list()
        print(f"✅ Authentication successful")
        print(f"✅ Access to {len(projects)} projects")
        return True
    except Exception as e:
        print(f"❌ Authentication failed: {e}")
        return False

if __name__ == "__main__":
    success = test_auth()
    sys.exit(0 if success else 1)

Security Monitoring

API Key Usage Monitoring:

# Monitor API key usage
import logging
from honeyhive import HoneyHive

# Set up security logging
security_logger = logging.getLogger('honeyhive.security')
security_logger.setLevel(logging.INFO)

# Log authentication attempts
client = HoneyHive(api_key="hh_your_key")
security_logger.info(f"HoneyHive client initialized with key: {client.api_key[:8]}***")

Anomaly Detection:

Monitor for unusual patterns: - API calls from unexpected IP addresses - High volume of requests - Failed authentication attempts - Access to unauthorized resources

Key Rotation Monitoring:

# Track key age and rotation
import datetime
from honeyhive.utils.auth import get_key_info

key_info = get_key_info()
key_age = datetime.datetime.now() - key_info['created_at']

if key_age.days > 90:
    print("⚠️ API key is older than 90 days - consider rotation")

See Also