Skip to main content

Partner Integration API Keys

Partners assigned to one or more domains can generate server-to-server API keys from Aventora Admin without platform-wide administrator access. Keys are scoped to a single domain and its billing account, and are intended for integration use (billing, provisioning lookups, and engagement) — not for platform administration.

Where to manage keys​

  1. Sign in to Aventora Admin as a partner_admin user.

  2. Select the assigned domain (if you manage more than one).

  3. Open Integration Keys in the sidebar, or navigate to:

    /domains/{domain}/integration-keys

You will see two sections:

Key typeScopeTypical use
Engagement HubBound to the domain admin's Hub billing account_idCredits, billing plan, usage, /start, /integration/start
Domain-ChatbotBound to the domain slugToken generation, queries, domain metadata, billing-context lookups

The API key secret is shown once at creation. Store it securely; it cannot be retrieved later.

Hub partner integration keys​

Permissions​

Hub keys created from the partner view use the partner_integration profile:

  • call_management — start engagements (POST /start, POST /integration/start)
  • account_management — read balance, usage, billing plan for the bound account
  • billing_management — top up credits, update billing plan on the bound account

They do not include:

  • admin or * (no cross-account or platform-wide access)
  • api_key_management (cannot create or revoke other keys via API)
  • Account registration (POST /accounts/register is blocked)
  • Free billing plans (requires super-admin JWT)

Create (admin UI)​

Partners create keys in the Admin UI. The server calls Hub:

POST /api-keys/partner-integration
Authorization: Bearer {HUB_API_KEY}
Content-Type: application/json

{
  "name": "Acme billing integration",
  "account_id": "{hub_account_uuid}",
  "partner_id": "{partner_id}",
  "description": "Partner integration key for acme"
}

Response (secret shown once):

{
  "success": true,
  "api_key": "…plaintext…",
  "key_info": {
    "key_id": "…",
    "name": "Acme billing integration",
    "account_id": "…",
    "permissions": {
      "permissions": ["call_management", "account_management", "billing_management"],
      "key_profile": "partner_integration"
    }
  }
}

Example: read account balance​

GET /accounts/me
Authorization: Bearer {partner_integration_key}

The account is resolved automatically from the key; do not pass a different account_id.

Example: add credits​

POST /accounts/credits/add
Authorization: Bearer {partner_integration_key}
Content-Type: application/json

{
  "account_id": "{same_account_as_key}",
  "amount": 100,
  "description": "Partner top-up"
}

When using an account-bound key, use the account tied to the key.

Example: start an engagement​

POST /integration/start
Authorization: Bearer {partner_integration_key}
Content-Type: application/json

{
  "phone_number": "+15551234567",
  "domain_name": "acme",
  "instruction": "Follow up on billing inquiry"
}

domain_name must match the domain whose billing account the key is bound to.

List and revoke​

Partners only see and revoke keys they created (filtered by partner_id attribution).

GET /api-keys?account_id={uuid}&key_profile=partner_integration&created_by_partner_id={partner_id}
Authorization: Bearer {HUB_API_KEY}
DELETE /api-keys/{key_id}?created_by_partner_id={partner_id}
Authorization: Bearer {HUB_API_KEY}

Domain-Chatbot partner integration keys​

Permissions​

Keys are standard domain-scoped integration keys (is_admin=false). They can access Domain-Chatbot APIs for that domain (for example token generation and queries). They cannot:

  • Provision new domains (POST /regenerate-index/provision-domain)
  • Create platform-wide admin keys
  • Access other domains

Partner API (domain-chatbot)​

Authenticated as partner_admin with access to the domain:

GET /api/partners/domains/{domain}/api-keys
Authorization: Bearer {partner_admin_jwt}
POST /api/partners/domains/{domain}/api-keys
Authorization: Bearer {partner_admin_jwt}
Content-Type: application/json

{
  "name": "Acme DC integration",
  "description": "Optional description",
  "expires_in_days": 365
}
DELETE /api/partners/domains/{domain}/api-keys/{key_id}
Authorization: Bearer {partner_admin_jwt}

Partners only see keys where partner_id matches their organization.

Example: billing context lookup​

GET /api/partners/domains/acme/billing-context
Authorization: Bearer {domain_scoped_api_key}

Use the domain-scoped key only for domains that match the key's domain field.

Admin API bridge​

Aventora Admin exposes partner-scoped routes (JWT + domain access check):

MethodPathAction
GET/api/partner/domains/{domain}/integration-keys/hubintegration-keys.read
POST/api/partner/domains/{domain}/integration-keys/hubintegration-keys.create
DELETE/api/partner/domains/{domain}/integration-keys/hub/{id}integration-keys.revoke
GET/api/partner/domains/{domain}/integration-keys/domain-chatbotintegration-keys.read
POST/api/partner/domains/{domain}/integration-keys/domain-chatbotintegration-keys.create
DELETE/api/partner/domains/{domain}/integration-keys/domain-chatbot/{id}integration-keys.revoke

These routes resolve the domain's Hub billing account via the domain admin's external_user_id (same pattern as partner billing).

Rollout​

Partner integration keys follow the same feature flags as Partner Management. With flags disabled, authorization actions are not enforced and behavior matches the pre-partner baseline.

Changelog​

DateChange
2026-07-06Partner Integration Keys: per-domain UI in Admin, Hub partner_integration key profile, Domain-Chatbot partner API key CRUD with partner_id attribution.

See also: