Authentication

Every request to the ODEN API is authenticated with an API key, sent as a bearer token.

The Authorization header#

Pass your key in the Authorization header on every request:

POST /search HTTP/1.1
Host: api.oden-api.com
Authorization: Bearer oden_live_your_key_here
Content-Type: application/json

There is no other auth scheme — no query-string keys, no basic auth, no cookies. A missing, malformed or revoked key returns X0.

Getting a key#

Sign in at oden-api.com/app and generate a key from the dashboard. Keys are prefixed oden_live_ so they are easy to spot in logs, monitoring dashboards, and secret scanners. Every account starts on the free tier with 1,000 searches a month.

Managing keys across environments#

A key can spend your quota, so treat it like a password:

• Never ship a key in client-side code — not in a browser bundle, a mobile app, or a public repository. Anyone who extracts it can drain your quota.
• Proxy from your backend if a browser or mobile app needs results. Your backend holds the key and calls ODEN; the client calls your authenticated backend.
• Inject via environment variables or secret management platforms rather than hardcoding.

Cloudflare Workers#

Store your key encrypted as a Cloudflare secret:

npx wrangler secret put ODEN_KEY
# Enter your secret key when prompted

Access it directly from your environment bindings in your worker handler:

export default {
  async fetch(request, env) {
    const odenKey = env.ODEN_KEY;
    // Call api.oden-api.com with Bearer token
  }
};

AWS & Docker Compose#

In Docker Compose, reference variables declared in your hosting environment or local .env file:

services:
  agent-api:
    image: my-company/agent-service:latest
    environment:
      - ODEN_KEY=${ODEN_KEY}

For AWS ECS or Kubernetes, fetch credentials at startup from AWS Secrets Manager or HashiCorp Vault.

Zero-downtime key rotation#

To rotate a key in production without service interruptions, follow this staged rollout procedure:

1. Generate a new key: Open the ODEN dashboard and create a secondary key.
2. Verify the new key: Run a validation script against the live API to confirm valid permissions.
3. Deploy the new key: Update your secret manager or environment configuration across your server fleet.
4. Revoke the old key: Once traffic has transitioned to the new key, delete the old key in the dashboard.

import requests

def verify_new_key(candidate_key: str) -> bool:
    """Validate a newly generated key before deploying to production."""
    resp = requests.post(
        "https://api.oden-api.com/search",
        headers={"Authorization": f"Bearer {candidate_key}"},
        json={"query": "health check", "answer": False, "depth": "basic"},
        timeout=10,
    )
    return resp.status_code == 200

A deleted key stops working immediately. If a key is accidentally committed or leaked, delete it immediately from the dashboard before generating a replacement.

Leaked key prevention & pre-commit hooks#

To prevent accidental git commits containing active credentials, add regex scanning rules to your pre-commit workflow (e.g., using gitleaks or detect-secrets):

# .gitleaks.toml configuration snippet
[[rules]]
id = "oden-api-key"
description = "Detected ODEN API Live Key"
regex = '''oden_live_[0-9a-zA-Z_-]{20,}'''
tags = ["key", "oden"]

Handling 401 errors programmatically#

A 401 Unauthorized status indicates a bad or missing token and should never be retried automatically. Trigger an alert to your engineering team immediately:

if response.status_code == 401:
    logger.critical("ODEN authentication failed. Verify ODEN_KEY environment variable.")
    alert_oncall_engineer("ODEN 401 Unauthorized error detected in production.")
    raise PermissionError("Invalid ODEN API key")

Environment segregation & multi-key isolation#

For security posture management, maintain strict isolation between environments:

• Development & staging keys: Issue dedicated keys for continuous integration test suites and local sandboxes. This prevents staging test runs from exhausting production search quotas.
• Production keys: Keep production keys strictly confined to secured server environments and production Kubernetes or Cloudflare secrets.
• Audit logging: Record all key creation, deletion, and rotation events within your team audit log. You can review timestamped key generation logs at any time from your account management console.

Next steps#

• Make a call: Search endpoint.
• Understand quotas: Rate limits.