Skip to main content

API Key Authentication

For Data Analysts

API keys provide a simple and effective way to authenticate server-to-server communications, scripts, and automated workflows with Olytix Core.

Overview​

API keys are long-lived credentials that:

  • Authenticate requests to Olytix Core APIs
  • Support scope-based permissions
  • Can be rotated without affecting other credentials
  • Are ideal for service accounts and automation

Creating API Keys​

Via CLI​

# Create a basic API key
olytix-core auth create-key --name "Analytics Pipeline"

# Create with specific scopes
olytix-core auth create-key --name "Read Only Service" --scopes read

# Create with expiration
olytix-core auth create-key --name "Temporary Access" --expires 30d

# Create with full access
olytix-core auth create-key --name "Admin Service" --scopes read,write,admin

Output:

API Key Created:
  Key: olytix-core_key_abc123xyz789def456ghi
  Name: Analytics Pipeline
  Expires: 2026-01-20
  Scopes: read

Store this key securely. It will not be shown again.

Via API​

curl -X POST http://localhost:8000/api/v1/auth/keys \
  -H "Authorization: Bearer YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics Pipeline",
    "scopes": ["read"],
    "expires_in_days": 365
  }'

Response:

{
  "key": "olytix-core_key_abc123xyz789def456ghi",
  "name": "Analytics Pipeline",
  "scopes": ["read"],
  "expires_at": "2026-01-20T00:00:00Z",
  "created_at": "2025-01-20T12:00:00Z"
}

Using API Keys​

curl -X POST http://localhost:8000/api/v1/query \
  -H "Authorization: Bearer olytix-core_key_abc123xyz789def456ghi" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["monthly_revenue"],
    "dimensions": ["orders.region"]
  }'

Query Parameter​

curl "http://localhost:8000/api/v1/query?api_key=olytix-core_key_abc123xyz789def456ghi" \
  -H "Content-Type: application/json" \
  -d '{
    "metrics": ["monthly_revenue"]
  }'

API Key Scopes​

Scopes control what actions an API key can perform:

ScopePermissions
readQuery data, read metadata, explore lineage
writeModify definitions, run models, update cubes
adminFull access including security settings, user management

Scope Examples​

# Read-only access for dashboards
olytix-core auth create-key --name "Dashboard Service" --scopes read

# Read and write for data pipelines
olytix-core auth create-key --name "ETL Pipeline" --scopes read,write

# Full admin access for management tools
olytix-core auth create-key --name "Admin Console" --scopes read,write,admin

Configuration​

Environment Variables​

# API key prefix (all keys start with this)
OLYTIX_SECURITY__API_KEY_PREFIX=olytix-core_key_

# Require authentication for all endpoints
OLYTIX_SECURITY__REQUIRE_AUTH=true

# Maximum API key lifetime (days)
OLYTIX_SECURITY__API_KEY_MAX_LIFETIME=365

# Enable API key caching
OLYTIX_SECURITY__API_KEY_CACHE_TTL=300

Project Configuration​

# olytix-core_project.yml
security:
  api_keys:
    enabled: true
    prefix: "olytix-core_key_"
    max_lifetime_days: 365
    require_expiration: true

    # Default scopes for new keys
    default_scopes:
      - read

    # Rate limiting per key
    rate_limit:
      requests_per_minute: 1000
      requests_per_hour: 50000

Managing API Keys​

List Keys​

olytix-core auth list-keys

Output:

API Keys:
  Name                  Created      Expires      Scopes      Status
  Analytics Pipeline    2025-01-20   2026-01-20   read        Active
  ETL Pipeline          2025-01-15   2025-07-15   read,write  Active
  Old Service           2024-06-01   2025-01-01   read        Expired

Revoke a Key​

# Revoke by name
olytix-core auth revoke-key --name "Analytics Pipeline"

# Revoke by key prefix
olytix-core auth revoke-key --key "olytix-core_key_abc123"

Rotate a Key​

# Rotate generates a new key and revokes the old one
olytix-core auth rotate-key --name "Analytics Pipeline"

Output:

Key Rotated:
  Old Key: olytix-core_key_abc123... (revoked)
  New Key: olytix-core_key_xyz789...
  Name: Analytics Pipeline
  Expires: 2026-01-20

User Attributes with API Keys​

API keys can include user attributes for RLS and masking policies:

# Create key with user attributes
olytix-core auth create-key \
  --name "Regional Service" \
  --scopes read \
  --user-id "service-na" \
  --roles "analyst,regional_viewer" \
  --attributes '{"region": "north_america", "department": "sales"}'

These attributes are included in the security context for policy evaluation:

# Security context from API key
SecurityContext:
  user:
    user_id: "service-na"
    roles: ["analyst", "regional_viewer"]
    attributes:
      region: "north_america"
      department: "sales"

Security Best Practices​

Storage​

  1. Never commit API keys to version control

    # .gitignore
    .env
    *.key
    credentials/

  2. Use environment variables

    export OLYTIX_API_KEY="olytix-core_key_abc123xyz789"

  3. Use secrets management in production

    # Kubernetes secret
    apiVersion: v1
    kind: Secret
    metadata:
      name: olytix-core-credentials
    type: Opaque
    data:
      api-key: dWFtcF9rZXlfYWJjMTIz...

Rotation​

  1. Set expiration dates - All keys should have a defined lifetime
  2. Rotate regularly - Rotate keys at least annually
  3. Rotate immediately if compromised - Revoke and regenerate immediately

Monitoring​

  1. Monitor usage patterns - Alert on unusual API key activity
  2. Track key lifecycle - Monitor creation, usage, and expiration
  3. Audit access logs - Review which keys access which data

Error Handling​

Invalid API Key​

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

Causes:

  • Key does not exist
  • Key has been revoked
  • Key prefix is incorrect

Expired API Key​

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}

Solution: Generate a new key or extend the expiration.

Insufficient Scope​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks required scope: write"
  }
}

Solution: Create a new key with the required scopes.

Integration Examples​

Python​

import requests

API_KEY = "olytix-core_key_abc123xyz789"
BASE_URL = "http://localhost:8000/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/query",
    headers=headers,
    json={
        "metrics": ["monthly_revenue"],
        "dimensions": ["orders.region"]
    }
)

data = response.json()

Node.js​

const axios = require('axios');

const API_KEY = process.env.OLYTIX_API_KEY;
const BASE_URL = 'http://localhost:8000/api/v1';

const client = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

async function queryMetrics() {
  const response = await client.post('/query', {
    metrics: ['monthly_revenue'],
    dimensions: ['orders.region']
  });
  return response.data;
}

Next Steps​