Partner Management API

Partner management enables multi-tenant support for billing and administrative operations through role-based access control.

Overview

Partner management in Aventora Admin allows:

• Partner account provisioning with dedicated role-based access
• Scoped billing visibility so partners see only their account data
• Administrative delegation to partner admins without super-admin privileges
• Staged rollout with dark-mode observation before enforcement

Architecture

Partner management uses a centralized authorization policy engine with staged rollout controls:

1. Policy evaluation — Centralized authorization policy engine in Aventora Admin
2. Role resolution — Backward compatible with existing is_admin + domain signals
3. Staged enforcement — Dark-mode observation, followed by optional enforcement
4. Observability — Structured audit events and metric counters

Feature flags

All partner features are gated by environment variables, all defaulting to false:

Flag	Purpose	Scope
PARTNER_MANAGEMENT_ENABLED	Master gate for partner code paths	Server
PARTNER_MANAGEMENT_ACCESS_GRANT_ENABLED	Allow partner account provisioning	Server
PARTNER_MANAGEMENT_DARK_AUTH_MODE_ENABLED	Observe-only policy enforcement	Server
PARTNER_MANAGEMENT_ENFORCE_AUTH_MODE_ENABLED	Enforce deny policies (returns 403)	Server
NEXT_PUBLIC_PARTNER_MANAGEMENT_ENABLED	Show partner UI to clients	Client
NEXT_PUBLIC_PARTNER_MANAGEMENT_ACCESS_GRANT_ENABLED	Enable partner access grant workflows	Client

Protected billing routes

Partner authorization is enforced on these API routes when flags enable it:

Route	Action	Description
GET /api/billing/account	billing.account.read	Fetch account data
PATCH /api/billing/account	billing.account.update	Update account settings
GET /api/billing/usage-summary	billing.usage-summary.read	Fetch usage summary
GET /api/billing/usage-report	billing.usage-report.read	Export usage CSV
GET /api/billing/purchases	billing.purchases.read	Fetch purchase history
GET /api/partner/domains/{domain}/integration-keys/hub	integration-keys.read	List Hub partner integration keys
POST /api/partner/domains/{domain}/integration-keys/hub	integration-keys.create	Create Hub partner integration key
DELETE /api/partner/domains/{domain}/integration-keys/hub/{id}	integration-keys.revoke	Revoke Hub partner integration key
GET /api/partner/domains/{domain}/integration-keys/domain-chatbot	integration-keys.read	List Domain-Chatbot partner keys
POST /api/partner/domains/{domain}/integration-keys/domain-chatbot	integration-keys.create	Create Domain-Chatbot partner key
DELETE /api/partner/domains/{domain}/integration-keys/domain-chatbot/{id}	integration-keys.revoke	Revoke Domain-Chatbot partner key

Partners manage keys in the Admin UI at Integration Keys (/domains/{domain}/integration-keys). See Partner Integration API Keys for key scopes and HTTP examples.

User roles

Partner management supports four role levels:

Role	Description	Billing Access
super_admin	Full platform access	All operations
partner_admin	Partner account management	All operations
domain_admin	Single domain management	Denied for partner actions
viewer	Read-only access	Denied for partner actions

Response format

Success (allowed)

Protected routes return their normal response when authorization passes.

Denied (enforce mode only)

When enforce mode is enabled and a policy denies access:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Forbidden",
  "code": "PARTNER_AUTHORIZATION_DENIED",
  "action": "billing.account.read",
  "reason": "role-not-allowed-for-partner-action"
}

Audit and monitoring

Structured audit events

Partner authorization emits structured JSON events for observability:

Audit event prefix: [partner-auth][event]

{
  "event": "partner_authorization_decision",
  "timestamp": "2026-06-22T10:30:00Z",
  "action": "billing.account.read",
  "role": "domain_admin",
  "allowed": false,
  "wouldDenyIfEnforced": true,
  "reason": "role-not-allowed-for-partner-action",
  "darkAuthModeEnabled": true,
  "enforceAuthModeEnabled": false,
  "userId": "user123",
  "userEmail": "user@example.com",
  "userDomain": "example.com",
  "partnerId": null,
  "requestId": "req-abc123",
  "correlationId": "corr-xyz789",
  "method": "GET",
  "path": "/api/billing/account",
  "host": "admin.aventora.ai",
  "runtime": "server"
}

Metric counters

Partner authorization emits counter metrics for aggregation:

Metric prefix: [partner-auth][metric]

Metric	Incremented	Description
partner_auth_would_deny_total	In dark mode, when policy would deny	Track deny candidates before enforcement
partner_auth_denied_total	In enforce mode, when request is denied	Track active denials

Each metric event includes action, role, reason, and request correlation fields.

Implementation guide

For integrators

When calling protected routes in partner scenarios:

1. Authenticate with user token via existing auth mechanism
2. Include headers: x-request-id, x-correlation-id (optional, for tracing)
3. Handle 403 responses with code: PARTNER_AUTHORIZATION_DENIED
4. Fallback gracefully in client when access is denied

Example:

curl -X GET https://admin.aventora.ai/api/billing/account \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "x-request-id: req-12345" \
  -H "x-correlation-id: trace-xyz"

For Aventora operations

See Partner Management Rollout (Internal) for staging, monitoring, and production activation procedures.

Backward compatibility

Partner management is fully backward compatible:

• All feature flags default to false
• When disabled, routes behave identically to before
• No response schema changes; new fields are optional in auth types
• Existing admin/domain logic is preserved as fallback

Error handling

Common error scenarios:

Scenario	HTTP Status	Code	Action
Invalid token	401	(standard auth)	Retry with valid token
Partner access denied (enforce mode)	403	PARTNER_AUTHORIZATION_DENIED	Inform user or escalate
Billing API unavailable	500	(standard error)	Retry or check backend status

Changelog

Date	Change
2026-07-06	Partner Integration API Keys: partners can create/list/revoke Hub and Domain-Chatbot keys per assigned domain from /domains/{domain}/integration-keys. See Partner Integration API Keys.
2026-07-02	Partner user invite (POST /api/partners/{id}/invite) re-invites existing accounts: resets password, assigns partner, and sends invitation email instead of returning 401. Returns 400 if the user belongs to a different partner.

---

Next steps:

• For deployment and monitoring, see Partner Management Rollout (internal docs)
• For general API authentication, see Platform API Keys
• For CRM integration, see CRM Webhooks