Request Context¶

The request context system is responsible for resolving and attaching the active organization to each request.

It enables multi-tenant isolation by ensuring that all operations are scoped to a specific organization.

Purpose¶

The request context system answers:

Which organization is this request operating in?
Is the user allowed to access this organization?
Should this request be allowed to proceed?

It ensures that:

users only access data within their organizations
superusers can access all organizations
all downstream logic receives a consistent request.org

Core Concept¶

Each request may include headers that define the active organization:

X-ORG-SLUG
X-ORG-ID
X-CUSTOMER-ORG-ID

These headers are resolved into:

request.org (internal org)
request.organization (alias)
request.customer_org (customer org)

Resolution Flow¶

flowchart TD
    A[Incoming Request] --> B[Read Headers]
    B --> C{Header Present?}
    C -->|No| D[Return None]
    C -->|Yes| E[Fetch Org]
    E --> F{Org Exists & Active?}
    F -->|No| G[Return None]
    F -->|Yes| H{User Allowed?}
    H -->|No| G
    H -->|Yes| I[Attach to request]

Resolution Rules¶

Header Priority¶

X-ORG-SLUG is preferred over X-ORG-ID
If both are present, slug is used

Org Validation¶

An organization must be:

existing
active

Otherwise:

resolution fails
request.org remains None

User Access Rules¶

Superuser¶

can access any active organization

Normal user¶

must have an active OrgMembership

If the user is not a member:

resolution fails

Customer Org Rules¶

For customer orgs:

X-CUSTOMER-ORG-ID is required
org must have type = customer
user must have active CustomerMembership (unless superuser)

Attaching to Request¶

Resolution is applied via:

attach_current_org(request)
attach_current_customer_org(request)

These functions:

resolve the org
attach it to the request
return the resolved org (or None)

Middleware Integration¶

The middleware:

CurrentOrgMiddleware

initializes request.org and request.customer_org
delegates resolution to the service layer

This keeps middleware lightweight and testable.

Permission Layer Integration¶

Permissions rely on request context.

Example:

HasCurrentOrg

checks if request.org is already set
attempts resolution if not
denies access if resolution fails

This ensures:

all protected endpoints require a valid org
no endpoint accidentally bypasses tenant isolation

Usage in Views¶

Views should never manually resolve orgs.

Instead:

rely on HasCurrentOrg permission
use request.org directly

Example:

org = request.org

Usage in Services¶

Services should:

receive org explicitly (preferred), or
use objects already scoped to org

Avoid:

accessing request directly inside services
re-resolving org inside services

Failure Behavior¶

If resolution fails:

request.org remains None
permissions will reject access

Typical response:

403 Forbidden

This ensures consistent handling across the API.

Security Considerations¶

The request context system is critical for:

tenant isolation
preventing cross-org data access
enforcing membership boundaries

All endpoints that operate on org data must:

use HasCurrentOrg (or equivalent)
rely on request.org

Common Mistakes¶

❌ Bypassing `request.org`¶

Do not:

query objects without filtering by org
manually fetch org without validation

❌ Resolving org inside services¶

Services should not:

parse headers
access request directly

❌ Forgetting permissions¶

Endpoints must include:

HasCurrentOrg

or

HasCurrentCustomerOrg

Example Flow¶

Request arrives with X-ORG-SLUG
Middleware initializes request
Permission triggers resolution
Org is validated
request.org is set
View uses request.org
Service executes within org scope

Benefits¶

The request context system provides:

consistent tenant scoping
centralized validation
simplified service logic
improved security

Future Extensions¶

The system can be extended with:

caching org resolution
multi-org context support
org switching helpers
request tracing across services

Summary¶

The request context system is the foundation of multi-tenant behavior.