Multi-Tenant Isolation
AI-in-a-Box enforces tenant boundaries at the gateway, service request context, storage keys, and audit verification layers.
Trust Boundary
The gateway is the trust boundary for external traffic. It removes inbound identity headers, validates the bearer token, then stamps trusted downstream headers.
Manual X-Tenant-ID headers from external callers are not authoritative. Configure the identity provider to emit the desired tenant claim.
Isolation Layers
| Layer | Mechanism |
|---|---|
| Gateway | Header stripping, JWT validation, tenant derivation, admin path guard. |
| Principal | HMAC-signed X-Aibox-Principal verified by Python services. |
| CapToken | Short-lived capability token bound to tenant, principal, scope, and turn. |
| Memory | Structured scope with tenant_id, user_id, optional agent_id, and session_id. |
| Knowledge | Tenant plus private/shared/restricted visibility and audience filtering. |
| Audit | Per-tenant hash chain, turn event storage, and receipt proof queries. |
Admin Authorization
Audit and admin routes distinguish tenant and platform operations:
tenant_admincan access a matching tenant.platform_adminand legacyadmincan perform cross-tenant operations.usercannot call/v1/admin/*.
Knowledge Visibility
Knowledge items are not just tenant-scoped. They also carry visibility metadata:
| Field | Meaning |
|---|---|
visibility_mode | Private, shared, or restricted policy. |
owner_user_id | Owning user. |
audience_tags | Groups allowed to read restricted content. |
user_grants | Explicit user grants. |
Search and list operations build actor context from tenant, user, and roles before filtering readable documents.
Audit Receipts
Turn receipt APIs require X-Tenant-ID and only return data for that tenant:
curl "http://localhost:8080/v1/receipts/$TURN_ID" \
-H "Authorization: Bearer $TOKEN"
The receipt proof is valid for the exported tenant chain suffix and the signing keys used to verify it.