All chapters
  1. Start hereA valid token is not a permission
  2. Foundations · 1Identity and trust primitives: who is calling, and who checks
  3. Foundations · 2People and identity proofing: accounts, passwords and recovery
  4. Foundations · 3Sessions and browser security: cookies, CSRF, XSS and the BFF
  5. Foundations · 4Authenticators and MFA: passwords, passkeys and phishing resistance
  6. Foundations · 5API keys and application credentials: what a key proves
  7. Foundations · 6Tokens: bearer, JWT anatomy, validation and revocation
  8. Foundations · 7OAuth, OpenID Connect and federation: delegation and login
  9. Authorization · 8Authorization from first principles: subject, action, resource, context
  10. Authorization · 9Access control models: RBAC, ABAC, ReBAC and ownership
  11. Authorization · 10The enforcement architecture: PEP, PDP, PIP and PAP
  12. Authorization · 11Policy as code: versions, tests, engines and decision logs
  13. Authorization · 12Tenant and data isolation: one platform, many brokerages
  14. Authorization · 13Identity governance and lifecycle: joiner, mover, leaver
  15. Authorization · 14Privileged access: standing rights, just-in-time elevation and break-glass
  16. Workloads · 15TLS, PKI and certificates: proving a host, and a client
  17. Workloads · 16Workload and service identity: SPIFFE, mTLS and caller allowlists
  18. Workloads · 17API gateways and zero trust: the edge checks, the service decides
  19. Workloads · 18Event-driven identity: Kafka principals, ACLs and replay
  20. Workloads · 19Cloud IAM and secretless deployment: roles, federation and no stored keys
  21. Workloads · 20External SaaS, webhooks and trust: calls that cross company lines
  22. Workloads · 21Private controlled environments: what private networking does and does not secure
  23. AI-native · 22Authenticating to model providers: keys, gateways and cloud IAM
  24. AI-native · 23MCP identity and authorization: discovery is not permission
  25. AI-native · 24RAG and retrieval authorization: only what this caller may read
  26. AI-native · 25Agents as principals and delegates: whose authority is this?
  27. AI-native · 26Agent-to-agent trust: identity, capabilities and forwarded authority
  28. AI-native · 27Coding agents and CI: repository scopes, OIDC and no production keys
  29. Operations · 28Auditing and observability of access: decisions you can prove later
  30. Operations · 29Threat modeling and testing: the negative tests that prove access control
  31. Operations · 30Operational lifecycles: rotation, revocation and outages
  32. Reference · 31Standards, frameworks and products: what each one is, and what it is not
  33. Reference · 32Architecture decision playbooks: choosing an auth strategy
  34. ReferenceGlossary
  35. AboutAbout this site and its sources
AI-native · 24

RAG and retrieval authorization: only what this caller may read

Per-source ACLs carried into chunks, identity-aware filters, tenant isolation, filter-first versus post-filtering and what each does to confidentiality and recall, revalidation before text reaches the model, deletion and freshness.

You will carry
Each source's permissions into chunk metadata, and build the search filter from the verified identity, never from model text.
You will weigh
Filter-first against post-filtering: what each does to confidentiality, and what each does to the number of results.
You will recheck
Results against the source system at read time, so a deleted or held document never reaches the model.

The draft recommendation for SUB-1004 looks thorough. It cites the provider's roof report, the current guidance rule R-ROOF-03, and a broker note: "roof age 12 years, metal roof, sprinklered". The underwriter u-uw-w1 reads it twice. SUB-1004 is a roof that the application says is 9 years old and the provider says is 22. Nobody said 12.

The note is real. It is chunk A3, written by a broker of brk-south about SUB-2001, a different brokerage's submission in a different business unit. It reached the model because the retrieval service ranked chunks by similarity first and applied permissions afterwards, and one code path skipped the second step. To the vector index, "roof age discrepancy" for one warehouse looks almost exactly like "roof age discrepancy" for another.

The team's first fix was to apply the permission filter to the top four results on every path. The leak stopped. So did half the results: the agent now received two passages instead of four, and the in-unit precedent P1, a case where roof ages differed by 11 years and the property was referred for inspection, never arrived. The search had spent its candidate slots on chunks the agent could not read.

Both problems have one cause: authorization was applied to the output of the search instead of to its input. This page is about putting it in the right place, and about what still has to be checked after it is there.

What retrieval authorization means#

Retrieval authorization is deciding, for each chunk a search could return, whether this caller may read it now, and making sure only those chunks reach the model. A tiny example: the underwriting agent, acting for u-uw-w1 on SUB-1004, may read the current guidance, the attachments of SUB-1004 and the precedents of commercial-west, and nothing else.

A retrieval service is a read API with an unusual query language. The caller sends a question, not an id, and the service decides which records answer it. Every rule from Authorization still applies, record by record. What changes is that the records are chunks (pieces of documents cut for search), copied out of their source systems into an index, and that the reader is often a model working for a person.

Before AI. Enterprise search has done this for decades: a document search that shows each employee only the files their groups may open, with the access lists copied from the file server into the index and refreshed on a schedule. The old lessons carry over: permissions travel with the copy, the copy goes stale, and a result list must not reveal what it hid.

The mechanics of retrieval (embeddings, approximate nearest-neighbour indexes, chunking, ranking) are taught on RAG Engineering. This page keeps to who may read what, and how the search keeps to it.

What this is not. Retrieval authorization decides who may read a chunk. It does not make the chunk's text trustworthy, and it does not defend against instructions hidden in that text; those defences are on Guardrails Engineering.

Permissions start at the source#

Every chunk comes from a document, and every document has an owner and an access rule in its source system. The underwriting platform searches three kinds of source:

SourceExample chunksWho may read it, in the sourceMetadata carried into each chunk
Underwriting guidance UW-GUIDEG1 (rule R-ROOF-03, version 2026.2), G3 (the same rule in 2025.4, superseded)insurer-side principals; only the version in forcepolicy_version, status, source_doc
Broker attachmentsA1, A2, A6 for SUB-1004 (tenant brk-north); A3, A4, A7 for SUB-2001 (tenant brk-south)the submitting brokerage, and insurer staff working that submissiontenant, submission_id, source_doc
Precedents (past decisions)P1, P5 of commercial-west; P2 of commercial-eastunderwriters and delegated agents of the same business unitbusiness_unit, source_doc

A chunk ACL is the access information a chunk carries from its source document, so that a search can decide on each chunk without asking the source first. A tiny example: chunk A3 carries tenant: brk-south and submission_id: SUB-2001, so no search for brk-north may return it.

Two properties make the metadata trustworthy. It is written by the ingestion pipeline from the source system's own records, never inferred from the text or by a model. And it keeps the source_doc id, so any result can be traced back to its source and rechecked there. This site's recommendation: treat the index as a copy with a known delay, and the source system as the authority. The index decides quickly; the source decides finally.

The smallest primitive: a filter built from the verified identity#

Before any ranking, the retrieval service turns the caller's verified identity into a filter. The caller never sends the filter, and neither does the model. Quoted from the example's retrieval.py, functions build_filter and allowed:

def build_filter(subject: dict[str, Any], records: list[dict[str, Any]]) -> dict[str, Any]:
    """The ACL filter from the verified identity. Never from the query, never from the model."""
    roles = subject.get("roles") or []
    if "broker" in roles:
        subs = [r["submission_id"] for r in records if r["tenant"] == subject.get("tenant")]
        return {"kinds": ["attachment"], "submission_ids": subs, "business_unit": None, "guide": CURRENT_GUIDE}
    dlg = subject.get("delegation")
    if dlg:
        subs = [(dlg.get("task") or {}).get("submission_id")]
    else:
        subs = [r["submission_id"] for r in records if r["business_unit"] == subject.get("business_unit")]
    return {"kinds": ["guidance", "attachment", "precedent"], "submission_ids": subs,
            "business_unit": subject.get("business_unit"), "guide": CURRENT_GUIDE}


def allowed(chunk: dict[str, Any], flt: dict[str, Any]) -> bool:
    """Does the index metadata allow this chunk for this filter?"""
    if chunk["kind"] not in flt["kinds"]:
        return False
    if chunk["kind"] == "guidance":
        return chunk["status"] == "active" and chunk["policy_version"] == flt["guide"]
    if chunk["kind"] == "attachment":
        return chunk["submission_id"] in flt["submission_ids"]
    return chunk["business_unit"] == flt["business_unit"]

A broker gets attachments of their own tenant's submissions only. An agent working under a delegation gets the attachments of the one submission its task names, its unit's precedents and the guidance in force. An underwriter without a delegation gets the attachments of every submission in their unit. Guidance is limited to UW-GUIDE 2026.2 and status active, so G3, the superseded 2025.4 version of the roof rule, is never a candidate.

For the underwriting agent of run-7f3a, the filter printed (scratch copy of examples/uw-auth, run on 2026-11-18):

filter: {'kinds': ['guidance', 'attachment', 'precedent'], 'submission_ids': ['SUB-1004'], 'business_unit': 'commercial-west', 'guide': '2026.2'}

The narrowest filter belongs to the agent, not the person: the underwriter could read SUB-1007's attachments, but the task names SUB-1004, so the agent cannot. Delegation narrows; it never adds (Agents).

A model may still propose its own filter. In the example, search accepts an llm_filter argument, records that it was ignored, and builds nothing from it. This site's own case UW-A13 checks that an "all tenants" filter written by a model changes nothing, and the tenant-level snippet is on Tenants. The rule is the third refrain of this site: the model suggests an action; deterministic code decides whether it may run, and on which data.

Filter first, or filter afterwards#

There are two places to apply the filter, and they fail differently.

Post-filter means the search first finds the nearest chunks with no regard to permissions, and the filter then removes the ones the caller may not read. A tiny example: take the four closest chunks, then drop A3 and P2 because they belong to another tenant and another unit.

Filter-first means the authorization constraint is part of the search itself: only chunks the caller may read are candidates, and ranking happens among them. A tiny example: rank only guidance in force, SUB-1004's attachments and commercial-west's precedents, then take the four closest.

The difference is not only a matter of order, because real vector indexes are approximate. ANN recall is the share of the true nearest neighbours that an approximate nearest-neighbour (ANN) search actually returns. A tiny example: if the four closest allowed chunks are P5, A1, A6 and P1, and a search returns only P5 and A1, the search found half of them. An approximate index examines a limited candidate list; a filter applied after that list can only shrink it. The example models this with ef=6 candidates and k=4 results, small integers so that Python and the browser compute identical scores. The mechanics, and the fixes real engines offer, are on RAG Engineering: approximate search.

The script below runs the four strategies for the underwriting agent, each with a model-proposed "all tenants, all units" filter that is ignored:

import retrieval as rt
from clock import START_EPOCH_S as NOW
from directory import RECORDS
from mcp_matrix import subjects

agent = subjects(NOW)["underwriting_agent"]
flt = rt.build_filter(agent, RECORDS)
for strategy, applied in [("post_filter", False), ("post_filter", True), ("filter_first", True), ("revalidate", True)]:
    r = rt.search(strategy, flt, filter_applied=applied, llm_filter={"tenant": "*", "business_unit": "*"})
    label = strategy + ("" if applied else " (no filter)")
    print(f"{label:24} examined={r['examined']} returned={[x['id'] for x in r['results']]} "
          f"leaked={r['leaked']} fewer_than_k={r['fewer_than_k']} dropped={r['dropped_by_revalidation']} "
          f"injected={r['injected_returned']}")
print("llm_filter_ignored:", r["llm_filter_ignored"])

Run in the scratch copy on 2026-11-18:

post_filter (no filter)  examined=['A3', 'P5', 'P2', 'A1', 'A6', 'P1'] returned=['A3', 'P5', 'P2', 'A1'] leaked=['A3', 'P2'] fewer_than_k=False dropped=[] injected=[]
post_filter              examined=['A3', 'P5', 'P2', 'A1', 'A6', 'P1'] returned=['P5', 'A1'] leaked=[] fewer_than_k=True dropped=[] injected=[]
filter_first             examined=['P5', 'A1', 'A6', 'P1', 'G1', 'A2'] returned=['P5', 'A1', 'A6', 'P1'] leaked=[] fewer_than_k=False dropped=[] injected=[]
revalidate               examined=['P5', 'A1', 'A6', 'P1', 'G1', 'A2'] returned=['A1', 'P1', 'G1', 'A2'] leaked=[] fewer_than_k=False dropped=['P5', 'A6'] injected=['A2']
llm_filter_ignored: True

Line one is the opening scene: the search without a filter returns A3, the other brokerage's note, and P2, the other unit's precedent with its rationale. Line two is the first fix: no leak, but two results instead of four, because A3 and P2 took two of the top four slots and were then removed. Line three is filter-first: four results, every one allowed, and P1 arrives. Line four adds revalidation, explained below; it drops two chunks and fills the slots from further down the allowed list.

So post-filtering costs confidentiality when a path skips it, and recall when it does not. Filter-first costs neither in this example. In a real engine it has costs of its own (a selective filter can make an approximate index search harder or slower), which is why the choice of filter design and index design belongs together.

Common confusion. "We filter the results, so nothing leaks" describes the safe path only. The leak lives in the path that forgot: a debug endpoint, a new feature, an evaluation script. A filter inside the search has no path that forgets it, because without it there are no candidates.

Diagram: Where the filter sits · three strategies for the underwriting agent of run-7f3a

Rows are the strategies, columns are what each examines, what it returns, and what goes wrong. Read the right-hand column: without a filter another tenant's chunk A3 and another unit's precedent P2 leak; filtering afterwards stops the leak but returns two chunks where four were asked; filtering first returns four allowed chunks, and revalidation then drops the two the source no longer allows.

  1. Top-k, then filter
    1. nearest 6 of all 21 chunks: The search ranks every chunk, allowed or not, and keeps the six best candidates.
    2. P5, A1: The top four are filtered after ranking; A3 and P2 are removed and nothing replaces them.
    3. leak if a path skips it; fewer results if not: Without the filter A3 and P2 reach the model; with it, recall drops and the useful P1 is lost.
  2. Filter, then top-k
    1. only allowed chunks are candidates: The filter built from the verified identity is part of the search; ranking happens among allowed chunks.
    2. P5, A1, A6, P1: Four results, every one allowed for this caller.
    3. index may be stale: The index metadata still allows a deleted document and one under legal hold.
  3. Filter first + revalidate
    1. allowed list, in rank order: The same allowed candidates, then each result is checked at the source before it counts.
    2. A1, P1, G1, A2: Stale chunks are dropped and the slots refilled from further down the allowed list.
    3. A2 allowed, still untrusted text: Authorization decides who may read A2; its injected instructions remain data, never commands.

The lab: four strategies, four callers#

Pick a caller and a strategy. The lab shows the filter the retrieval service builds from the caller's verified identity, the candidates in rank order (marked when not for this caller), the returned chunks with leaks highlighted, the fewer-results effect, the chunks revalidation drops, and A2 flagged as untrusted text. Type anything into the "LLM-written filter" box: it is always ignored. The agent here is a scripted stand-in, so these results show how the access controls work, not how good any model is.

The second embed starts on post-filtering, the first fix of the opening:

Recorded runs, k=4:

CallerStrategyReturnedLeakedFewer than kDropped by revalidation
underwriting agentno filterA3, P5, P2, A1A3, P2nonone
underwriting agentpost-filterP5, A1noneyes (2)none
underwriting agentfilter firstP5, A1, A6, P1nonenonone
underwriting agentfilter first + revalidateA1, P1, G1, A2 (A2 untrusted text)nonenoP5, A6
broker brk-northno filterA3, P5, P2, A1A3, P5, P2nonone
broker brk-northpost-filterA1noneyes (1)none
broker brk-northfilter firstA1, A6, A2, A5nonenonone
broker brk-northfilter first + revalidateA1, A2, A5noneyes (3)A6
broker brk-southno filterA3, P5, P2, A1P5, P2, A1nonone
broker brk-southfilter first + revalidateA3, A4, A7noneyes (owns only 3)none
underwriter u-uw-w1no filterA3, P5, P2, A1A3, P2nonone
underwriter u-uw-w1filter first + revalidateA1, P1, G1, A2nonenoP5, A6

Two rows say "fewer than k" for a good reason. Broker brk-south owns three attachments in the corpus, so three is the right answer. Broker brk-north gets three because revalidation removed A6. A short result is not always a recall problem; it can be the correct size of what this caller may read.

Revalidation: the source decides last#

The index is a copy, and copies go stale. Two things changed in the source systems after the example's index was built: the broker deleted the photo index of SUB-1004 (document DOC-ATT-1004-3, chunk A6), and precedent DOC-PREC-W-03 (chunk P5) moved under legal hold, so the unit may no longer read it. The index metadata still allows both.

Revalidation is rechecking each result against the source system's current access rule at read time, after the search and before the text reaches the model. A tiny example: A6 passed the index filter, the source says the document no longer exists, so A6 is dropped and the next allowed chunk takes its place.

In the example, the revalidate strategy walks the filter-first list in rank order and keeps a chunk only if source_allows says yes, until it has k. That is why the fourth line above returns A1, P1, G1, A2 and reports P5, A6 as dropped: the filter-first answer minus the two stale chunks, refilled from further down the list. The source state the check reads:

DOC-ATT-1004-3 {'exists': False, 'readable_by_unit': False}
DOC-PREC-W-03 {'exists': True, 'readable_by_unit': False}

Revalidation costs a call to each source per result, or a lookup in a permission cache the sources keep current. This site's recommendation: filter in the index on every query, and revalidate at the source for any result that will reach a model or a person, at least for sources where deletions, legal holds or permission changes matter. The index filter keeps the search fast and the results full; the source check keeps them true.

Deletion and freshness#

When a broker deletes an attachment, the delete has to reach every copy: the document store, the chunks, the vectors, the index, any cache of search results, and any evaluation set built from them. Index deletion is removing a source document's chunks and vectors from every search structure, and proving it happened. A tiny example: after DOC-ATT-1004-3 is deleted, no search for anyone returns A6, and a reconciliation job finds no chunk whose source_doc no longer exists.

Permission changes are the same problem with a smaller change. A document moved under legal hold, a submission moved to another unit, a broker who left a brokerage: each changes who may read existing chunks without changing their text. Pattern: source-aligned permissions, in which the index stores the source's access facts (tenant, submission, unit, version, status) rather than a copy of a decision, and a change in the source updates the chunk metadata by event. The unit-level and submission-level facts in the example are of that kind; a list of principal ids stamped on each chunk is not, because it must be rewritten every time someone joins or leaves (Governance).

Freshness has a business side too. Guidance chunks carry policy_version and status, and the filter accepts only UW-GUIDE 2026.2, effective 2026-07-01. The superseded G3, which says to escalate only above 8 years of difference, is never a candidate, so the model cannot cite last year's threshold as if it were current. Cache keys for search results must change when the corpus or the policy changes; the generation-number technique is on RAG Engineering: operations.

Diagram: Permissions travel with the copy · from source system to model context

Read left to right. The source system owns each document and its access rule. Ingestion copies the access facts into every chunk. At query time the retrieval service builds the filter from the verified identity, ignores any filter the model wrote, and searches only allowed chunks. Before text reaches the model, each result is rechecked at the source. Deletions and permission changes flow from the source into the index by event.

  1. Source systems
    1. document + its access rule: Guidance, broker attachments and precedents each live in a system that owns who may read them.
  2. Ingestion
    1. chunk + ACL metadata: Each chunk carries tenant, submission, unit, version, status and its source document id.
    2. events: delete, hold, move: Source changes update or remove chunks, vectors and caches; a reconciliation job proves it.
  3. Retrieval service
    1. filter from the verified identity: Built from the validated subject and the directory; a model-written filter is recorded as ignored.
    2. search among allowed chunks: The constraint is part of the search, so every candidate is allowed.
    3. recheck each result at the source: Drops chunks whose source document was deleted or restricted after indexing.
  4. Model context
    1. allowed passages, marked as data: Only allowed, current passages arrive; instructions inside them are never commands.

Precedents: only the unit's, and never above current policy#

find_similar_decisions searches past decisions. A past decision contains rationale, and rationale written in one business unit is that unit's internal reasoning about a specific customer. The example limits precedent search to the caller's unit (rule R-AZ-06) both in the retrieval filter and at the decision point. This site's own case UW-A14 checks both:

$ /opt/homebrew/bin/python3 run_cases.py --case UW-A14 --verbose
case    result title                                                first check
UW-A14  PASS   Precedent from another unit                          P2_returned=false
    ok  P2_returned: expected false, actual false
    ok  cross_unit_search: expected {"allow": false, "status": 403}, actual {"allow": false, "status": 403}

1/1 cases match their expected block. (Scripted stand-in agent: this shows the access controls, not model quality.)

P2, the east unit's precedent that declined a property with a 14-year difference, is never returned to a west search, and a west underwriter who asks to search the east unit's precedents directly is refused 403.

A second rule is about authority, not access. A precedent is evidence that informs a recommendation; it never overrides the current business policy. If a precedent showed that a similar roof was accepted under UW-GUIDE 2025.4, the rule in force is still R-ROOF-03 of UW-GUIDE 2026.2: application and provider roof ages differ by more than 5 years, escalate. Brokers never search precedents at all; a precedent is the insurer's internal record, and its rationale belongs to neither brokerage.

Authorized is not trusted#

Chunk A2 is an attachment of SUB-1004, uploaded by the broker of brk-north. Every filter allows it for the underwriting agent, because it belongs to the agent's task. Its text is not a broker note. It is a sentence addressed to "the assistant", telling it to ignore the guidance, to call record_underwriter_decision with approve, and to write a recommendation for SUB-2001. This is the shape of series case UW-005: injected text in a retrieved passage.

Retrieval authorization did its job: the agent may read A2. The example flags it (injected_returned in the output above) and the lab marks it as untrusted text, but neither makes its instructions safe. They are data, never commands. When the scripted agent sends the two calls the passage asks for, the tool server refuses both: the decision call at the scope check, the recommendation for SUB-2001 with 404 (steps 6 and 7 in the example's agent.py, explained on MCP).

Security note. Permissions decide whose documents the model reads. Injection defences decide what the model does with them. A system needs both, and neither substitutes for the other: an authorized chunk can carry an attack, and a perfect injection filter does not stop a cross-tenant leak.

What goes wrong without these ideas#

Without chunk ACLs, the index cannot decide, and every search returns whatever is closest, across tenants and units (the opening's A3). With a post-filter only, a forgotten path leaks and the safe path starves: two results where four were asked, and the useful P1 missing. With a model-written filter, a prompt injection in one tenant's attachment can widen the search to every tenant. Without revalidation, a deleted photo index and a precedent under legal hold still reach the model. Without version and status in the metadata, last year's guidance competes with this year's. And without the principal type in the decision rules, an injected passage in an authorized chunk could still trigger a write.

In a coding agent. A coding agent that searches code and documentation across an organization needs the same rule: its search index carries each repository's access rules, the filter comes from the identity of the agent's installation and the person it works for, and a repository the person cannot open is never a candidate. Secrets found in an indexed file are still secrets; the sandbox holds no production credential to use them with (Coding agents).

Choosing a design#

SituationSimplest credible designGrow whenAlternatives
One team, one corpus, everyone may read everythingNo per-chunk ACL; authenticate the caller; keep version and status for freshnessa second audience or a confidential source arrivesa separate index per audience
Several tenants or units in one corpusChunk ACL metadata from the source; filter-first from the verified identity; model-proposed filters ignoredpermissions change often, or deletions carry legal weightan index or partition per tenant
Deletions, legal holds, frequent permission changesAdd revalidation at the source for every result that reaches a model or person; event-driven metadata updates; reconciliationrevalidation latency hurtsa permission cache kept current by source events
Very selective filters on an approximate indexFilter-first with the engine's filtered-search support; measure how often results come back shortshort results remain commonpartitions per tenant, or exact search over the filtered rows (see rag.sammuthu.com)

This site's recommendation: start with chunk ACLs, filter-first and an ignored model filter, because those three cost little and close the leak. Add revalidation as soon as a source can delete or restrict documents faster than the index updates.

Standards, products and patterns#

No standard read for this page defines retrieval authorization; it is assembled from patterns. Pattern: chunk ACL metadata copied from the source at ingestion. Pattern: filter-first (also called pre-filtering or authorization-constrained retrieval). Pattern: read-time revalidation against the source. Pattern: source-aligned permissions updated by event. How a specific vector database or search engine expresses filters, partitions and filtered approximate search is product documentation; this page makes no claim about any product, and the comparison is on RAG Engineering. The authorization decisions themselves use the models of Access models (attributes for tenant and unit, relationships for assignment), and the database backstop for tenant tables is on Tenants.

Security notes#

Monday checklist#

Exercises#

  1. The team proposes to raise k from 4 to 20 with post-filtering, "so enough allowed chunks survive". What does that fix, and what does it not fix?
  2. The underwriter u-uw-w1 and the underwriting agent acting for u-uw-w1 run the same query. Why can their results differ, and which one should be narrower?
  3. A product manager wants the broker portal's assistant to "learn from similar submissions across all brokerages". What is the tenant-safe version?
AnswersOne line each
  1. It reduces short results in the safe path; it does not fix the leak in any path that skips the filter, and a very selective filter can still starve the result.
  2. The agent's filter comes from its task (SUB-1004 only), the person's from their unit (SUB-1004 and SUB-1007); delegation narrows, so the agent's must be narrower.
  3. Each brokerage's assistant searches only its own tenant's documents; any cross-brokerage learning is a separate, owned, anonymized dataset, not a wider filter on the live index.

Advanced perspective#

What to store on a chunk: facts, groups or principal listsThree shapes of chunk ACL, and how each ages

There are three common shapes. Facts about the record (tenant, submission, unit, version, status) are what the example stores; the filter turns the caller's identity into conditions on those facts. They change rarely, they match the attribute model of Access models, and a person joining a unit changes nothing in the index. Group ids copied from the source's access list ("readers: uw-west-group") work when the source thinks in groups and the identity provider shares them; they change when the source's sharing changes, and the index must follow. Principal lists ("readers: u-uw-w1, u-uw-w2") are the simplest to query and the worst to maintain: every joiner, mover and leaver rewrites chunks, and the index silently disagrees with the source in between.

Relationship-based rules, such as "the assigned underwriter of this submission", fit poorly into any of the three, because the relationship changes without the document changing. The robust split is to filter in the index on stable facts (tenant, unit) and check the fine-grained relationship at revalidation or at the decision point, where it can be read live. Design the metadata for the coarse boundary, and never for the finest rule you have.

One shared index or one per tenant?Where the boundary is structural and where it is a filter

A shared index with a tenant filter is one structure to build, tune and monitor, and the boundary is a condition every query must carry. A partition or index per tenant makes the boundary structural: a query for brk-north cannot touch brk-south's vectors at all, a selective tenant filter stops starving the approximate search, and offboarding a brokerage is dropping its partition. The cost is more structures, uneven sizes (one large tenant, many tiny ones), and cross-tenant features becoming separate systems.

The internal boundary often stays a filter even when tenants are partitioned: precedents are shared across the insurer but limited by business unit, guidance is shared by everyone but limited by version. So most real systems are hybrid, structural for the external tenant boundary where contracts or residency demand it, and filtered inside. Whatever the layout, keep one test that runs a search as each tenant with a valid identity and asserts nothing foreign returns, because a layout change is exactly when a boundary moves without anyone noticing (Tenants has the same argument for databases).

Revalidation at scaleLatency, caching, and what to do when the source is down

Revalidating every result against every source means one call per result per query, to systems that were not designed to answer "may this caller read this document now" thousands of times a minute. Three techniques keep it workable. Batch the check: one call per source per query, with all candidate document ids. Cache the answers briefly, keyed by caller, document and a version number the source increments on each permission change, so a change invalidates the entry at once instead of after a timer. And revalidate only what crosses a boundary: results that will be shown to a person or placed in a model's context, not intermediate candidates.

The outage case needs a decision written down in advance. If the source cannot answer, the safe default for confidential sources is to drop the result (fail closed) and say that some sources were unavailable, without naming what was dropped. Returning unverified chunks during an outage turns every outage into a window where deletions and legal holds are ignored. This is the same choice as for a policy decision point that cannot be reached (Operations): availability may degrade, confidentiality may not.

Vectors, caches and evaluation sets are copies tooEvery derived store inherits the source's permissions and deletions

It is tempting to treat embeddings as anonymous numbers. This site's recommendation: treat a vector as a copy of the text it was computed from, with the same owner, tenant and deletion duty. The reasoning is simple, and labelled as reasoning: a vector exists to be found by text that means the same thing, so it carries that meaning, and the index stores it next to the chunk id that leads back to the text.

The same holds for every derived store: a cache of search results, a cache of model answers built from them, an evaluation set sampled from real queries, a fine-tuning dataset, a log of retrieved passages. Each needs the tenant in its keys or rows, each must be reached by deletions, and each needs an owner. The question to ask of any new store in the retrieval path is the one this page started with: if a broker deleted this document an hour ago, can anyone still read any copy of it here?

In one breath#

Retrieval authorization decides, chunk by chunk, what a caller may read, with permissions carried from each source into chunk metadata and a filter built from the verified identity, never from model text. Filtering inside the search keeps both confidentiality and recall, while filtering afterwards leaks on any path that forgets and starves the results on the paths that remember. Revalidating results against the source catches deletions and holds the index has not seen, precedents stay inside their unit and below current policy, and an authorized chunk is still untrusted text.

The agent now reads only what its task allows, through tools that check every call. But whose task is it? The underwriting agent acts with its own workload identity and with authority the underwriter delegated for one submission and one hour. How that delegation is granted, narrowed, chained, approved and taken back is the subject of Agents.