Skip to main content

Platform API Keys Configuration Guide

This document explains the API key architecture for the Aventora platform.

Overview​

The Aventora platform consists of multiple microservices that communicate via REST APIs. The API key architecture follows this principle:

ONLY aventora-admin stores admin API keys in environment variables. All other servers store domain/account-specific API keys in their databases.

Architecture Principles​

  1. Admin API Keys (Platform-wide)

    • Storage: ONLY in aventora-admin/.env.local (Next.js app)
    • Purpose: Enable super admin operations across all services
    • Keys: DOMAIN_CHATBOT_API_KEY, HUB_API_KEY (platform-wide admin keys)
    • Rule: Python servers MUST NOT store or use admin API keys from environment variables

  2. Domain/Account-Specific API Keys

    • Storage: In each server's database
    • Purpose: Allow servers to call other servers on behalf of domains/accounts
    • Pattern: Server A stores Server B's API key for each domain/account it needs to act on behalf of
    • Rule: NO fallback to environment variables - if key not found in database, operation fails with clear error

API Keys Summary​

API KeyStored InUsed ByCallsRequired PermissionsNotes
HUB_API_KEYaventora-admin/.env.localaventora-adminAIventora-Phone APIadminPlatform-wide admin key
DOMAIN_CHATBOT_API_KEYaventora-admin/.env.localaventora-adminDomain-Chatbot APIadminPlatform-wide admin key
phone_api_keyCMS DB (tenants table)CMS backendAIventora-Phone APIVariesPer-tenant key
chatbot_api_keyCMS DB (tenants table)CMS backendDomain-Chatbot APIVariesPer-tenant key
phone_api_keyDomain-Chatbot DB (domains table)domain-chatbotAIventora-Phone APIVariesPer-domain key
domain_chatbot_api_keyPhone DB (accounts table)phone-serverDomain-Chatbot APIVariesPer-account key
internal_api_keyPhone DB (accounts table)phone-server (internal services)AIventora-Phone APIadminPer-account key for internal calls

Admin API Keys (aventora-admin Only)​

HUB_API_KEY​

Purpose: Authenticates requests from aventora-admin to the AIventora-Phone API (billing, accounts, calls, etc.)

Stored In: aventora-admin/.env.local ONLY

Required Permissions:

  • admin permission (full access)

Database: AIventora-Phone PostgreSQL database (api_keys table)

How to Generate​

cd AIventora-Phone
python utils/create_admin_key.py

This creates an admin-level API key with full permissions. Use the output as HUB_API_KEY.

Where to Configure​

aventora-admin (aventora-web-apps/aventora-admin/.env.local):

HUB_API_URL=http://localhost:8010
HUB_API_KEY=<your-generated-admin-key>

DOMAIN_CHATBOT_API_KEY​

Purpose: Authenticates requests from aventora-admin to the Domain-Chatbot API

Stored In: aventora-admin/.env.local ONLY

Required Permissions:

  • admin permission (platform-wide admin key)

Database: Domain-Chatbot database (domain_api_keys table)

How to Generate​

Create a platform-wide admin API key via domain-chatbot admin API:

POST /auth/admin/domain-api-keys
Authorization: Bearer <admin-jwt-token>
Content-Type: application/json

{
  "name": "PLATFORM_ADMIN_KEY",
  "description": "Platform-wide admin key for aventora-admin",
  "permissions": ["admin"],
  "expires_in_days": null
}

Where to Configure​

aventora-admin (aventora-web-apps/aventora-admin/.env.local):

NEXT_PUBLIC_DOMAIN_CHATBOT_API=http://localhost:8009
DOMAIN_CHATBOT_API_KEY=<your-generated-admin-key>

Domain/Account-Specific API Keys (Database-Stored)​

CMS Backend API Keys​

Storage: aventora-cms-backend database (tenants table)

chatbot_api_key​

  • Purpose: CMS backend calls Domain-Chatbot API on behalf of tenant
  • Column: tenants.chatbot_api_key
  • Generated: Via ensure-domain-cms-api-keys.ts script or manually

phone_api_key​

  • Purpose: CMS backend calls Phone API on behalf of tenant
  • Column: tenants.phone_api_key
  • Generated: Via ensure-domain-cms-api-keys.ts script or manually

Note: CMS backend does NOT use environment variables for these keys. Operations fail if keys are not set in database.

Domain-Chatbot API Keys​

Storage: domain-chatbot database (domains table)

phone_api_key​

  • Purpose: Domain-chatbot calls Phone API on behalf of domain
  • Column: domains.phone_api_key
  • Generated: Via ensure-domain-cms-api-keys.ts script or manually

Note: Domain-chatbot does NOT use HUB_API_KEY environment variable. Operations fail if phone_api_key is not set in database.

Phone-Server API Keys​

Storage: AIventora-Phone database (accounts table)

domain_chatbot_api_key​

  • Purpose: Phone-server calls Domain-Chatbot API on behalf of account
  • Column: accounts.domain_chatbot_api_key
  • Generated: Via ensure-domain-cms-api-keys.ts script or manually

internal_api_key​

  • Purpose: Phone-server internal services (bulk_call_service, email_pull_service) make authenticated calls to phone API endpoints
  • Column: accounts.internal_api_key
  • Permissions: admin
  • Generated: Must be created and stored when account is set up

Note: Phone-server does NOT use DOMAIN_CHATBOT_API_KEY or ADMIN_API_KEY environment variables. Operations fail if keys are not set in database.

Key Management Script​

The ensure-domain-cms-api-keys.ts script in aventora-admin automatically ensures API keys exist for a domain:

cd aventora-web-apps/aventora-admin
npm run ensure-cms-api-keys <domain_name>

This script:

  1. Checks if API keys exist in CMS database
  2. Creates missing keys in domain-chatbot and phone-server
  3. Updates CMS database with the keys

Requirements:

  • aventora-admin/.env.local must have DOMAIN_CHATBOT_API_KEY and HUB_API_KEY (admin keys)
  • Domain must exist in domain-chatbot
  • Account must exist in phone-server

Migration from Old Architecture​

Before: All servers stored API keys in environment variables with fallbacks.

After: Only aventora-admin stores admin keys in env vars. All other servers use database-stored keys with NO fallbacks.

Breaking Changes​

  1. CMS Backend: Removed DOMAIN_CHATBOT_API_KEY and HUB_API_KEY from environment variables. Must set chatbot_api_key and phone_api_key in tenants table.

  2. Domain-Chatbot: Removed HUB_API_KEY from environment variables. Must set phone_api_key in domains table.

  3. Phone-Server: Removed DOMAIN_CHATBOT_API_KEY and ADMIN_API_KEY from environment variables. Must set domain_chatbot_api_key and internal_api_key in accounts table.

Migration Steps​

  1. Run database migrations (automatic on server startup):

    • domain-chatbot: Adds phone_api_key column to domains table
    • phone-server: Adds domain_chatbot_api_key and internal_api_key columns to accounts table

  2. Populate API keys in databases:

    • Use ensure-domain-cms-api-keys.ts script for each domain
    • Or manually set keys via database updates

  3. Remove environment variables from Python servers:

    • Remove DOMAIN_CHATBOT_API_KEY from CMS, domain-chatbot, phone-server
    • Remove HUB_API_KEY from CMS, domain-chatbot
    • Remove ADMIN_API_KEY from phone-server

  4. Verify operations work:

    • Test cross-service calls
    • Verify error messages are clear when keys are missing

Error Handling​

When database-stored API keys are missing, operations fail with clear error messages:

  • CMS Backend: "Phone API key not configured for domain X. Please set phone_api_key in CMS tenant settings."
  • Domain-Chatbot: "Phone API key not configured for domain X - cannot create phone account"
  • Phone-Server: "Domain-chatbot API key not configured for account X. Please set domain_chatbot_api_key in account settings."
  • Phone-Server Internal Services: "No internal_api_key configured for account X - call will fail authentication"

No fallbacks to environment variables - operations fail immediately if database keys are not found.

Security Considerations​

  • Plain Text Storage: Domain/account-specific API keys are stored as plain text in database columns. This is acceptable because:

    • Keys are external service authentication tokens (similar to OAuth tokens)
    • Database access is already secured
    • Keys are account/domain-specific, limiting blast radius if compromised

  • Admin Keys: Platform-wide admin keys are stored ONLY in aventora-admin/.env.local and are NOT committed to version control.

  • Key Rotation: To rotate keys:

    1. Generate new keys via respective services
    2. Update database columns
    3. Update aventora-admin/.env.local for admin keys
    4. Restart affected services