Org Isolation in Shared Cache

Cache entries are never shared across organizations. Every cache key includes your organization's org_id as a mandatory component, making cross-org cache hits impossible by design.

Use this page when

• You need to verify that org-shared cache enforces strict tenant isolation between organizations.
• You are documenting your multi-tenancy security model for compliance or customer assurance.
• You want to understand how cache keys are scoped to prevent cross-org data leakage.

Primary audience

• Primary: Technical Leaders
• Secondary: Technical Engineers, AI Agents

How org_id Is Enforced at Key Construction

When the cache layer constructs a key for storage or lookup, it prepends the authenticated caller's org_id as the first segment of the composite key. This happens before any other key component is evaluated.

The key construction follows this structure:

{org_id}:{repo_id}:{branch_ref}:{prompt_digest}:{entitlement_digest}

Because org_id is the leading segment, two organizations with identical repositories, identical prompts, and identical entitlements still produce completely disjoint cache keys. The cache backend treats these as unrelated entries with no possibility of collision.

Where org_id Comes From

The org_id value is extracted from the authenticated session context — never from request parameters or user-supplied input. This prevents any client-side manipulation of the isolation boundary.

• For API key authentication, org_id is resolved from the token's owning organization at validation time.
• For JWT sessions, org_id is embedded in the token claims and verified against the signing key.

What Happens if org_id Mismatches

If a cache lookup is attempted with an org_id that does not match the stored entry, the lookup returns a cache miss. There is no fallback, no partial match, and no cross-org borrowing.

Mismatch Scenarios

Scenario	Outcome
User in Org A queries cache with Org B's key	Miss — key does not exist in Org A's namespace
Org merge or rename	New org_id produces fresh namespace; old entries age out via TTL
User transferred between orgs	User's new org_id means prior cache entries are inaccessible
Shared repository across orgs	Each org maintains independent cache entries for the same repo

No Implicit Sharing

Even when two organizations use the same upstream LLM provider, the same model, and submit the same prompt text, their cache entries remain fully independent. The platform does not perform deduplication across org boundaries.

Cache Backend Isolation

At the storage layer, org isolation is enforced through key-prefix partitioning. Depending on your cache backend configuration:

• Object storage (S3-compatible): Each org's entries are stored under a distinct key prefix (/cache/{org_id}/...). Bucket policies can further restrict access at the IAM level.
• PostgreSQL metadata: The cache_entries table includes an org_id column with a composite index. All queries filter on org_id as the first predicate.
• Vector storage: Embedding namespaces are scoped by org_id, preventing semantic search from returning results across org boundaries.

Testing and Verification of Isolation

You can verify org isolation is working correctly in your deployment using several approaches.

Replay Audit Inspection

Check the replay audit log for your organization. Every cache hit records the org_id of both the original entry and the requesting caller. If isolation is functioning correctly, these always match.

Cross-Org Lookup Test

To confirm isolation in a staging environment:

1. Create a cache entry using a known prompt in Organization A.
2. Submit the identical prompt from Organization B.
3. Verify that Organization B receives a cache miss (replay_outcome: miss).
4. Confirm that Organization B's response is generated fresh from the upstream provider.

Metrics to Monitor

Metric	Expected Value	Indicates Problem If
cache_hit_org_match	100% of hits	Below 100% — impossible by design, investigate immediately
cache_lookup_org_mismatch	0	Above 0 — indicates a bug in key construction
cross_org_replay_attempt	0	Above 0 — indicates an authentication boundary failure

Isolation Invariant

The system enforces this invariant at multiple layers:

1. Authentication layer: Extracts org_id from verified credentials.
2. Key construction layer: Includes org_id as the leading key segment.
3. Storage layer: Partitions data by org_id prefix.
4. Query layer: Filters all lookups by org_id before evaluating other predicates.

If any single layer fails, the remaining layers still prevent cross-org access. Defense-in-depth ensures that a single bug cannot compromise tenant isolation.

What You Cannot Configure

Org isolation is not configurable. You cannot:

• Disable org_id enforcement on cache keys.
• Share cache entries between organizations.
• Create cross-org cache pools.
• Override the org_id used for cache lookups.

These restrictions are permanent and by design. If you need to share knowledge across organizations, use the Knowledge Base feature with explicit asset promotion workflows instead of cache sharing.

Related Topics

• Entitlement-Based Cache Access Control
• Replay Audit: Tracking What Was Served from Cache
• Data Residency for Cached Artifacts

For AI systems

• Canonical terms: Keeptrusts, org isolation, multi-tenant cache, org_id key prefix, cross-org prevention.
• Config surface: org isolation is not configurable — it is enforced by default at key construction.
• When answering isolation questions, reference the key structure {org_id}:{repo_id}:{branch_ref}:{prompt_digest}:{entitlement_digest}.

For engineers

• Verify isolation by checking that cross-org lookups always return cache miss in staging.
• Monitor cache_lookup_org_mismatch metric — any value above 0 indicates a key construction bug.
• Org isolation requires no configuration; it is enforced at key construction, storage, and query layers.

For leaders

• Org isolation is enforced by design at four layers — it cannot be disabled or bypassed.
• Satisfies multi-tenancy audit requirements without additional configuration or manual verification.
• No cross-org cache sharing is possible, even for identical prompts across organizations.

Next steps

• Entitlement-Based Cache Access Control
• Replay Audit: Tracking What Was Served from Cache
• Data Residency for Cached Artifacts