docs(connectors): document ACL enforcement (PRO-3222 PRO-3223)

api-reference/v2/endpoint/connectors-overview.mdx

@@ -25,7 +25,7 @@ Check on it:
 
 Change it:
 
-- [Update Connector](/api-reference/v2/endpoint/update-connector): `PATCH /connectors/{id}` changes the sync interval, connector-level instructions or credentials.
+- [Update Connector](/api-reference/v2/endpoint/update-connector): `PATCH /connectors/{id}` changes the sync interval, connector-level instructions, credentials or the ACL enforcement setting.
 - [Update Connector Resource](/api-reference/v2/endpoint/update-connector-resource): `PATCH /connectors/{id}/resources/{resource_id}` changes one resource's instructions or access rule.
 - [Add Connector Resource](/api-reference/v2/endpoint/add-connector-resource): `POST /connectors/{id}/resources` adds one new resource.
 - [Delete Connector Resource](/api-reference/v2/endpoint/delete-connector-resource): `DELETE /connectors/{id}/resources/{resource_id}` stops syncing a resource.
@@ -37,7 +37,7 @@ Change it:
 2. `GET /connectors/{id}/discover` to see which resources are available.
 3. `POST /connectors/{id}/configure` with the resources to sync. This starts the first sync.
 4. `GET /connectors/{id}/status` until `status` is `healthy` and `lifecycle` is `active`.
-5. `POST /query` to search the database and collection chosen during configuration. For restricted content, send the caller’s identity as `acl`; omitting it leaves results unfiltered. `query_apps` is enabled by default.
+5. `POST /query` to search the database and collection chosen during configuration. For content from connectors without ACL enforcement, send the caller's identity as `acl`; omitting it leaves those results unfiltered. Enforced connectors use the authenticated caller instead. `query_apps` is enabled by default.
 
 After that, syncs run every `sync_interval_seconds` (one hour by default). Call `POST /connectors/{id}/sync` only when you need data sooner.
 
@@ -46,21 +46,23 @@ After that, syncs run every `sync_interval_seconds` (one hour by default). Call
 To change a resource that is already configured, use `PATCH /connectors/{id}/resources/{resource_id}` or `POST /connectors/{id}/configure`. `POST /connectors/{id}/resources` adds new resources only: on an existing `resource_id` it returns `409` and changes nothing.
 
 - Instructions or access rule on one resource: `PATCH /connectors/{id}/resources/{resource_id}`. Only the fields you send change.
-- Instructions, sync interval or credentials for the whole connector: `PATCH /connectors/{id}`. Only the fields you send change.
+- Instructions, sync interval, credentials or ACL enforcement for the whole connector: `PATCH /connectors/{id}`. Only the fields you send change. Only workspace owners and writers in a signed-in dashboard session can set `enforce_acl`; readers can view the current setting but cannot change it, and API keys cannot set it.
 - Name, type, database, collection or metadata of resources: `POST /connectors/{id}/configure`. Resources you leave out of the list are not touched. For each resource you list, send `name` and `resource_type` every time, because omitted values are cleared. Its sync position, instructions and access rule are kept.
 - A brand new resource: `POST /connectors/{id}/configure` or `POST /connectors/{id}/resources`.
 
 In paths, `{resource_id}` is the resource's id as returned by the Discover and List Resources endpoints, for example a Slack channel id or a Supabase `schema.table` name. URL-encode it when it contains spaces or other reserved characters.
 
 ## Authentication
 
-All connector endpoints use your HydraDB API key:
+Connector API requests use your HydraDB API key:
 
 ```http
 Authorization: Bearer $HYDRA_DB_API_KEY
 API-Version: 2
 ```
 
+To set `enforce_acl`, use a signed-in dashboard session for a workspace owner or writer instead; API-key-authenticated requests cannot set it.
+
 ## Key concepts
 
 - **Connector:** an authenticated connection to one external provider account. It owns every resource synced from that account.

api-reference/v2/endpoint/create-connector.mdx

@@ -12,6 +12,7 @@ Optional settings you can also pass here, and change later with [Update Connecto
 
 - `custom_instructions`: guidance for how this connector's documents are interpreted and indexed. See [Custom Ingestion Instructions](/essentials/v2/connectors#custom-ingestion-instructions).
 - `sync_interval_seconds`: how often scheduled syncs run. Omit it for the provider default (one hour for most providers).
+- `enforce_acl`: whether content reads always enforce ACL for the authenticated caller for this connector. It defaults to `false` when omitted. Only workspace owners and writers in a signed-in dashboard session can set it, and `true` requires the provider to report `acl_supported: true`. API-key-authenticated requests must omit this field. An owner or writer can enable or change it later with [Update Connector](/api-reference/v2/endpoint/update-connector) or in the dashboard. See [ACL on synced content](/essentials/v2/connectors#enforce-acl) for how caller identity and request `acl` behave.
 
 <RequestExample>
 
@@ -70,6 +71,7 @@ curl -X POST 'https://api.hydradb.com/connectors' \
   "provider_account_scope": "T12345ACME",
   "lifecycle": "pending_setup",
   "sync_status": "idle",
+  "enforce_acl": false,
   "sync_interval_seconds": 3600,
   "next_sync_at": "2026-06-01T12:05:00Z",
   "first_sync_at": "2026-06-01T12:05:00Z",
@@ -83,7 +85,7 @@ curl -X POST 'https://api.hydradb.com/connectors' \
 
 - `400`: `provider` or `database` is missing, the provider is unknown, or a setting such as `sync_interval_seconds` is out of range.
 - `402`: your plan's connector limit is reached.
-- `403`: the provider is not available to your organization.
+- `403`: the provider is not available to your organization, or the request tries to set `enforce_acl` without a signed-in dashboard session for a workspace owner or writer. The ACL authorization error message is `only workspace owners and writers can change ACL enforcement`.
 - `422`: `credentials` does not match the provider's `credential_schema`.
 
 <div className="api-before-related-resources" />

api-reference/v2/endpoint/fetch-content.mdx

@@ -49,7 +49,7 @@ curl -G 'https://api.hydradb.com/context/inspect' \
 | <Field name="collection" type="string or null" /> | Collection scope. If omitted, the default collection is used. |
 | <Field name="mode" type="&#x22;content&#x22; or &#x22;url&#x22; or &#x22;both&#x22;" /> | What to return. See [Fetch modes](#fetch-modes). (default=`"both"`) |
 | <Field name="expiry_seconds" type="integer" /> | TTL of the presigned URL (when `mode` includes `url`). Range `60` to `604800` (7 days). (default=`3600`) |
-| <Field name="acl" type="string[]" /> | Principals to answer as (document ACLs). A source they cannot see returns the same `404` as a missing one. Repeated (`acl=a&acl=b`) or comma-separated. Omit for no ACL scoping. See [Access Control](/essentials/v2/access-control). |
+| <Field name="acl" type="string[]" /> | Principals to answer as (document ACLs). A source they cannot see returns the same `404` as a missing one. Repeat or comma-separate values. Omit for no caller-supplied ACL filtering. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 
 ## Fetch modes
 

api-reference/v2/endpoint/list-connector-providers.mdx

@@ -53,6 +53,8 @@ TypeScript SDK 2.1.7 requires the explicit authorization header for this method.
       "supported": true,
       "moveit_support": false,
       "webhook_support": false,
+      "acl_supported": true,
+      "acl_description": "Captures channel-level access: public channels are visible to the whole workspace, private channels only to their members.",
       "is_alpha": false,
       "is_beta": false,
       "rank": 1
@@ -94,6 +96,8 @@ TypeScript SDK 2.1.7 requires the explicit authorization header for this method.
 
 Only providers you can connect are listed, so `supported` is always `true`. `webhook_support` is `true` for providers whose data arrives by webhook instead of scheduled syncs. `rank` is `null` for providers without a display position; they are listed last, alphabetically.
 
+`acl_supported` indicates whether the provider captures ACL as document access rules. When it is `true`, `acl_description` summarizes the captured ACL. `enforce_acl` can only be enabled for a connector when its provider reports `acl_supported: true`; see [ACL on synced content](/essentials/v2/connectors#enforce-acl).
+
 ## One provider
 
 - `credential_schema` is the JSON Schema for `credentials` on [Create Connector](/api-reference/v2/endpoint/create-connector) and [Update Connector](/api-reference/v2/endpoint/update-connector). It is omitted when unavailable.

api-reference/v2/endpoint/list-documents.mdx

@@ -76,7 +76,7 @@ curl -X POST 'https://api.hydradb.com/context/list' \
 | <Field name="page_size" type="integer" /> | Items per page, from `1` to `100`. (default=`50`) |
 | <Field name="filters" type="object" /> | Structured exact-match filters. See [Filters](#filters). (default=`null`) |
 | <Field name="include_fields" type="string[] or null" /> | Field projection. Only the listed fields plus `id`, `database`, `collection` are populated. Only applies to `type=knowledge`. (default=`null`, all fields) |
-| <Field name="acl" type="string[]" /> | Principals to list as (document ACLs). Only knowledge sources those principals may see come back. Omitted, `[]`, or `["*"]` lists everything. Ignored for `type=memory`. See [Access Control](/essentials/v2/access-control). |
+| <Field name="acl" type="string[]" /> | Principals to list as (document ACLs). Omitted, `[]`, or `["*"]` disables caller-supplied filtering. Ignored for `type=memory`. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 
 ### Filters
 

api-reference/v2/endpoint/query.mdx

@@ -316,7 +316,7 @@ result = client.query(
 | <Field name="collections" type="string[] or object" /> | Multi-collection scope. Send a list of collection IDs for equal weighting, or an object mapping collection ID to a positive relative weight (at most one decimal place, e.g. `{"finance": 1.5, "legal": 0.8}`) to bias ranking. Up to 100 collections. Do not combine with `collection`. |
 | <Field name="query" type="string" required /> | Query terms or natural-language question. Cannot be empty. Maximum 5,000 words. |
 | <Field name="titles" type="string[]" /> | Exact source titles, matched case-insensitively. Matches any listed title, then intersects with `ids` if both are sent. |
-| <Field name="acl" type="string[]" /> | Caller identities used to enforce document permissions. Omitting `acl`, sending `[]`, or sending `["*"]` disables permission filtering. See [Access Control](/essentials/v2/access-control). |
+| <Field name="acl" type="string[]" /> | Caller identities used to filter document ACLs. Omitting `acl`, sending `[]`, or sending `["*"]` disables caller-supplied filtering. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 | <Field name="response_format" type='"structured" or "markdown"' /> | Omit for the result object with `llm_prompt`. `"structured"` leaves out the prompt string. `"markdown"` returns the prompt string directly as `data`. |
 | <Field name="type" type='"knowledge" or "memory" or "all"' /> | What to query. `"all"` runs knowledge and memory in parallel over the same scope and merges by `relevancy_score`. (default=`"knowledge"`) |
 | <Field name="query_by" type='"hybrid" or "text"' /> | Retrieval method. See [Query methods](#decision-matrix). (default=`"hybrid"`) |
@@ -348,7 +348,7 @@ Metadata filters work like SQL `WHERE` clauses. Top-level `metadata_filters` key
 }
 ```
 
-See [Metadata and Filters](/essentials/v2/metadata#3-filter-operators) for operators and examples. Filters narrow results. They do not replace the caller's `acl`.
+See [Metadata and Filters](/essentials/v2/metadata#3-filter-operators) for operators and examples. Filters narrow results. They do not replace the caller's `acl` or connector ACL enforcement.
 
 ### Decision matrix
 

api-reference/v2/endpoint/source-relations.mdx

@@ -49,7 +49,7 @@ curl -G 'https://api.hydradb.com/context/relations' \
 | <Field name="collection" type="string or null" /> | Collection scope. If omitted, the default collection is used. |
 | <Field name="limit" type="integer" /> | Maximum relation groups to return. Range `1` to `10000`. (default=`5000`) |
 | <Field name="cursor" type="number or null" /> | Opaque pagination cursor from a previous response's `next_cursor`. (default=`null`) |
-| <Field name="acl" type="string[]" /> | Principals to answer as (document ACLs). Only relations from sources those principals may see are returned. Repeated (`acl=a&acl=b`) or comma-separated. Omit for no ACL scoping. See [Access Control](/essentials/v2/access-control). |
+| <Field name="acl" type="string[]" /> | Principals to answer as (document ACLs). Only relations from sources those principals may see are returned. Repeat or comma-separate values. Omit for no caller-supplied ACL filtering. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 
 <ResponseExample>
 

api-reference/v2/endpoint/subgraph.mdx

@@ -56,7 +56,7 @@ curl -G 'https://api.hydradb.com/context/slack_C0BE77_1788320073/subgraph' \
 | <Field name="type" type="&#x22;knowledge&#x22; or &#x22;memory&#x22;" /> | Which graph the `id` belongs to. The two graphs are completely separate. (default=`"knowledge"`) |
 | <Field name="depth" type="integer" /> | Maximum traversal depth in hops. Range `1` to `10`. (default=`5`) |
 | <Field name="max_sources" type="integer" /> | Maximum number of members returned. Range `1` to `1000`. When this clips the traversal, `is_truncated` is `true`. (default=`200`) |
-| <Field name="acl" type="string[]" /> | Principals to answer as (document ACLs). The subgraph then contains only items those principals may see, filtered at every hop. Repeated (`acl=a&acl=b`) or comma-separated. Omit for no ACL scoping. |
+| <Field name="acl" type="string[]" /> | Principals to answer as (document ACLs). Only items those principals may see are returned, filtered at every hop. Repeat or comma-separate values. Omit for no caller-supplied ACL filtering. For enforced connectors, the authenticated caller is used instead; see [ACL enforcement](/essentials/v2/connectors#enforce-acl). |
 
 ## How items connect
 

api-reference/v2/endpoint/update-connector.mdx

@@ -4,16 +4,25 @@ description: "Change a connector's instructions, sync interval or credentials in
 openapi: "api-reference/v2/openapi.json PATCH /connectors/{id}"
 ---
 
-Update a connector's instructions, sync interval, or credentials. Omitted fields keep their existing values.
+Update a connector's instructions, sync interval, credentials, or ACL enforcement. Omitted fields keep their existing values.
 
 - HydraDB validates every field before saving. Invalid input changes nothing.
 - Credentials are saved before other settings. If a server error occurs afterward, only the credentials may have changed. Retrying the same request is safe.
 
 - `custom_instructions` applies to resources without their own instructions. Maximum 4,000 characters. Send `""` to clear it. Changes affect future syncs. See [Custom Ingestion Instructions](/essentials/v2/connectors#custom-ingestion-instructions).
 - `sync_interval_seconds` reschedules the next sync. Stay within the returned `min_sync_interval_seconds` and `max_sync_interval_seconds`, or send `0` for the provider default.
 - `credentials` reconnects the existing connector. Send the provider's complete credential set. Resources and saved sync positions are preserved.
+- `enforce_acl` enables or disables caller-bound enforcement of this connector's captured ACL. Existing connectors remain `false` until an owner or writer enables it. Send `true` to enforce captured ACL on every content read, or `false` to return to opt-in request `acl` filtering. Omit it to keep the current value. The change takes effect on the next content request for already-synced documents and does not require re-ingestion. Only workspace owners and writers in a signed-in dashboard session can set it; `true` requires the provider to report `acl_supported: true`. API-key-authenticated requests cannot set it. See [ACL on synced content](/essentials/v2/connectors#enforce-acl) and [Access Control](/essentials/v2/access-control).
 
-Only these three fields can be updated. A connector's `name`, `database`, `collection` and `provider_account_scope` cannot be changed after creation. Omit them from the request; unsupported fields can cause a `400` response.
+To enable enforcement later, send this field in a PATCH request, or use **Enforce ACL** in the dashboard's connector settings:
+
+```json
+{
+  "enforce_acl": true
+}
+```
+
+Only `custom_instructions`, `sync_interval_seconds`, `credentials`, and `enforce_acl` can be updated. A connector's `name`, `database`, `collection` and `provider_account_scope` cannot be changed after creation. Omit them from the request; unsupported fields can cause a `400` response.
 
 <RequestExample>
 
@@ -57,6 +66,7 @@ curl -X PATCH 'https://api.hydradb.com/connectors/{id}' \
 {
   "connector_id": "{connector_id}",
   "sync_interval_seconds": 3600,
+  "enforce_acl": false,
   "next_sync_at": "2026-06-01T13:00:00Z",
   "min_sync_interval_seconds": 300,
   "max_sync_interval_seconds": 604800,
@@ -70,9 +80,11 @@ curl -X PATCH 'https://api.hydradb.com/connectors/{id}' \
 
 ## Errors
 
-- `400`: the request includes an unsupported field, `custom_instructions` is over 4,000 characters, or `sync_interval_seconds` is outside the provider's range. Nothing is changed.
+- `400`: the request includes an unsupported field, the provider does not report `acl_supported` for `enforce_acl: true`, `custom_instructions` is over 4,000 characters, or `sync_interval_seconds` is outside the provider's range. Nothing is changed.
+- `403`: the request tries to set `enforce_acl` without a signed-in dashboard session for a workspace owner or writer. The ACL authorization error message is `only workspace owners and writers can change ACL enforcement`.
 - `404`: no connector with this id in your organization.
 - `422`: `credentials` does not match the provider's `credential_schema`.
+- `503`: HydraDB could not read its provider catalog to check `acl_supported` for `enforce_acl: true`. Nothing is changed. Retry the request.
 
 <div className="api-before-related-resources" />