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 Key	Stored In	Used By	Calls	Required Permissions	Notes
HUB_API_KEY	aventora-admin/.env.local	aventora-admin	AIventora-Phone API	admin	Platform-wide admin key
DOMAIN_CHATBOT_API_KEY	aventora-admin/.env.local	aventora-admin	Domain-Chatbot API	admin	Platform-wide admin key
phone_api_key	Domain-Chatbot DB (domains table)	domain-chatbot	AIventora-Phone API	Varies	Per-domain key
domain_chatbot_api_key	Phone DB (accounts table)	phone-server	Domain-Chatbot API	Varies	Per-account key
internal_api_key	Phone DB (accounts table)	phone-server (internal services)	AIventora-Phone API	admin	Per-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)

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: Manually or via provisioning tooling

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: Manually or via provisioning tooling

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.

---

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. Domain-Chatbot: Removed HUB_API_KEY from environment variables. Must set phone_api_key in domains table.

2. 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:

   • Manually set keys via database updates or provisioning tooling

3. Remove environment variables from Python servers:

   • Remove DOMAIN_CHATBOT_API_KEY from domain-chatbot, phone-server
   • Remove HUB_API_KEY from 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:

• 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