Access Rules

An access rule narrows who in your workspace can see a document's content. Rules are scoped to a source, a document type, or a tag, and they are managed from the Access rules panel on a source card, or workspace-wide under Settings → Access rules.

Two principles govern the model, and both matter when reasoning about what a colleague can see. First, visibility is default-allow: a document that no rule matches is visible to everyone in the workspace. Second, a rule excludes — it never grants. There is no "allow rule" that opens a document to someone who could not otherwise reach it; adding a person to a rule only means they survive that rule.

New sources are private by default

When you connect a new source — Google Drive, Gmail, SharePoint, OneDrive, S3, Azure Blob, a SQL database, Notion, HubSpot, Granola — Talonic automatically applies a "Private source" rule to it. Its documents start visible only to you, the person who connected it. Sharing is then a deliberate act: edit the rule to name the colleagues or roles who should also see the source, or delete the rule to make it workspace-visible.

Who can connect a source depends on the connector, not on access rules. Personal connectors — Google Drive, Gmail, Outlook, OneDrive, and Granola — can be connected by any member; infrastructure connectors — SharePoint, Teams, Notion, HubSpot, Azure Blob, S3, and SQL databases — require a workspace owner. Either way, the resulting connection starts private to whoever connected it, so widening the connect permission never widens visibility: a member-connected Drive is exactly as private as an owner-connected one until its rule is edited.

Two source kinds are exempt and never receive an automatic rule, because they have no single connector to be private to: manual uploads and API sources (documents pushed through a dedicated API key). Existing connections made before this behavior shipped are untouched — there is no retroactive backfill.

How rules combine

Rules intersect. A document hidden by one rule stays hidden even if a second rule would admit you — every rule that matches the document must independently let you through. This is the safe direction: adding a rule can only ever narrow visibility, never widen it, so a new rule cannot accidentally expose something.

Each rule names its principals — who survives it. A principal is a specific person, a role (viewer, member, owner, and above), or the uploader (whoever connected the source or uploaded the document). The automatic "Private source" rule uses the uploader principal, which is why it resolves to exactly one person without naming them.

Managing rules through the API

Rules are managed at /iam/rules. A rule body carries a name, a condition_type of source_connection, document_type, or tag, the condition_value the rule matches on, and at least one principal. Principals are objects with a principal_type of user (with a user ID), role (with a role name), or uploader (no ID needed). GET /iam/templates lists the shipped rule templates — the same gallery the UI offers, including the private_source template applied automatically at connect time.

# Hide HR documents from everyone except the People team and owners
curl -X POST "$API_URL/iam/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HR documents - People team only",
    "condition_type": "document_type",
    "condition_value": "employment_contract",
    "principals": [
      { "principal_type": "user", "principal_id": "9f2c41d6-8a3b-4e0f-9c77-1d2e3f4a5b6c" },
      { "principal_type": "role", "principal_id": "owner" }
    ]
  }'

{
  "id": "5b1f9c2e-7d4a-4b3c-8e6f-0a1b2c3d4e5f",
  "name": "HR documents - People team only",
  "condition_type": "document_type",
  "condition_value": "employment_contract",
  "template_key": null,
  "created_by": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "created_at": "2026-08-12T10:31:44.902Z",
  "principals": [
    { "principal_type": "user", "principal_id": "9f2c41d6-8a3b-4e0f-9c77-1d2e3f4a5b6c" },
    { "principal_type": "role", "principal_id": "owner" }
  ]
}

# List rules to find the auto-applied "Private source" rule
curl "$API_URL/iam/rules" -H "Authorization: Bearer $TOKEN"

# Add a colleague to it (PATCH replaces the principals array)
curl -X PATCH "$API_URL/iam/rules/$RULE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "principals": [
      { "principal_type": "uploader" },
      { "principal_type": "user", "principal_id": "<colleague-user-id>" }
    ]
  }'

# Or delete the rule entirely to make the source workspace-visible
curl -X DELETE "$API_URL/iam/rules/$RULE_ID" \
  -H "Authorization: Bearer $TOKEN"

What a hidden document looks like

A hidden document is hidden everywhere its content could surface, not just in the document list. That includes search results and value autocomplete, extraction and captured values, structuring grids and run results, cases and their evidence, linking graphs, benchmark and validation results, the review queue, anomalies, and the AI agent's answers. The agent will not cite, quote, or count a document you cannot see.

A document you cannot see behaves as though it does not exist, rather than returning a "forbidden" error. This is deliberate: an error that distinguishes "hidden" from "missing" would itself reveal that the document exists. Counts and totals are computed from what you can see, so a filtered list does not disclose how much was withheld.

Who can manage rules

A rule can be edited or deleted by its author or by a workspace owner. Rule management is authorized against your real workspace membership, so it cannot be reached by assuming a role you do not hold in that workspace.

API keys and integrations

An API key sees exactly what the user who created it sees. A key minted by someone excluded from a source returns no documents from it — the public API applies the same rules as the interface. Keys created before this feature shipped, which carry no recorded creator, fail closed: they still return documents that no rule matches, but never a rule-matched one.

Current limits

• Outbound delivery and share links are not filtered. A scheduled delivery, a data-product export, or a public share link runs without a viewer, so it can carry documents that access rules would hide from an individual. Treat configuring a delivery or minting a share link as a sharing decision in its own right.
• Rules by document type or tag depend on that value being present. A document with no detected type matches no document-type rule, and a document with no tags matches no tag rule. For a guarantee that does not depend on classification, scope the rule to the source.
• Tags can move a document in and out of scope. Because a tag rule matches on tags, whoever can edit a document's tags can change which tag rules apply to it.
• Reference data imported from a SQL source stays workspace-visible. Rows already imported into a reference table are consumed workspace-wide by matching and resolution; access rules do not reach them.
• Assembled values with no source document stay visible. A value composed from several documents may have no single source document to match a rule against, so it remains visible under default-allow.