Tenant Context Standard¶

Purpose¶

The Tenant Context Standard defines how future API contracts represent and verify tenant and organization context.

Context Concepts¶

Concept	Meaning
TenantId	Platform tenant boundary for isolation and operational context.
OrganizationId	Customer business entity and organization-scoped resource boundary.
ActorId	User, service account, AIOS tool, or integration actor.
Membership	Identity-owned relationship between actor and OrganizationId.
Entitlement	Billing-owned access or limit attached to organization subscription state.

Rules¶

Tenant and organization context must be resolved before business work.
Organization-scoped APIs require OrganizationId.
Clients may provide context, but APIs must verify it against Identity and Organization records.
Tenant filtering is enforced server-side and is not an optional client filter.
Cross-tenant access is denied unless an explicit administration policy allows it.
Tenant and organization context must appear in audit records for material reads and commands.

Context Resolution Flow¶

flowchart LR
    Request[API Request]
    Token[Keycloak Token]
    Identity[Identity Membership]
    Organization[Organization Reference]
    Billing[Billing Entitlement]
    API[Domain API]

    Request --> Token
    Token --> Identity
    Identity --> Organization
    Organization --> Billing
    Billing --> API

Standard Metadata¶

Metadata	Requirement
`tenantId`	Required where tenant-scoped behavior applies.
`organizationId`	Required for organization-owned or organization-bound resources.
`actorId`	Required for authorization, audit, and approval.
`correlationId`	Required for workflow and integration traceability.
`causationId`	Required when request follows a prior event, command, or callback.

Error Behavior¶

Missing tenant context returns TENANT_CONTEXT_REQUIRED.
Missing organization context returns ORGANIZATION_CONTEXT_REQUIRED.
Unauthorized context returns TENANT_ACCESS_DENIED.
Entitlement denial returns ENTITLEMENT_REQUIRED or USAGE_LIMIT_REACHED.