Access Control

Restrict who can retrieve a document. Declare permissions yourself, or let connectors capture them from the source app.

By default every document in a collection is retrievable by every query against it. Access control changes that: a document can carry an access-control list (ACL): the identities allowed to retrieve it, and a query can carry the identity it is running on behalf of. HydraDB returns only the documents that identity is allowed to see.

This is what you need to build an internal search product where a query by one employee must not surface a private Slack channel or a restricted Drive file belonging to another.

Access control is opt-in per request. A query without an acl field is not filtered. Adding ACLs to your documents changes nothing until your queries start declaring who is asking.

---

1. The two halves

Access control only works when both halves are in place. Either half alone is a no-op.

Half	What it means	Where
Stamping	The document carries an allow-list.	Ingest, a metadata edit, a connector resource rule, or automatic capture from the source app.
Enforcement	The query declares who is asking.	The acl field on POST /query and POST /context/list.

---

2. Principals

A principal is an identity represented by a string: a user, a group, or everyone in a domain. These are the five supported forms:

Principal	Meaning
user_email:[e-mail]	One person, by email. A bare [e-mail] is accepted and normalized to this form.
domain:acme.com	Everyone whose email is under that domain. Matches automatically for any caller who queries with an email at that domain; you do not have to declare it on the query side.
group:<provider>:<id>	A group in the source app, for example group:slack:C0123 or group:google:[e-mail].
__public__	Every identified caller in the collection.
__private__	Nobody. The stored form of an explicitly empty allow-list.

Principals are lowercased, trimmed, and deduplicated on the way in. __public__ overrides everything else in the same list: a document that is public is public. A list containing __private__ alongside real principals keeps the real principals and drops the sentinel; __private__ only means something on its own.

An absent ACL and an empty ACL are not the same thing. A document with no acl is unrestricted. That is how every document ingested before you adopted access control behaves, and it is why adopting it never silently hides your existing content. A document you explicitly restrict to nobody is stored as __private__. Sending "acl": [] means “nobody”, not “everybody”.

Limits: 1000 principals per document, 256 characters per principal. For larger groups, use a group: or domain: principal.

---

3. Set an ACL

At ingest, on an app source

Each item in app_knowledge accepts an acl list:

{
  "id": "slack-C0123-1712345678",
  "kind": "message",
  "provider": "slack",
  "external_id": "1712345678.000100",
  "fields": { "kind": "message", "body": "Q3 comp bands are attached." },
  "acl": ["user_email:[e-mail]", "group:slack:C0123"]
}

Omit acl and the document is unrestricted. A malformed principal rejects the whole request with 400 rather than ingesting the document unprotected.

On an existing source, without re-ingesting

PATCH /context/{id}/metadata accepts acl and replaces the stored list:

curl -X PATCH 'https://api.hydradb.com/context/slack-C0123-1712345678/metadata' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "engineering",
    "acl": ["user_email:[e-mail]", "user_email:[e-mail]"]
  }'

Replace, not merge: to add a third person, send all three. The three wire states are distinct and all meaningful:

You send	Result
No acl key	The stored ACL is left untouched.
"acl": [...]	Replaced with exactly that list.
"acl": [] or "acl": null	Revoked. Nobody can retrieve it.

An acl-only body is a valid edit; you do not have to send metadata alongside it.

On a connector resource

Every object synced from a resource inherits the resource’s rule. Set it when you configure the connector:

{
  "resources": [
    {
      "resource_id": "C_LEADERSHIP",
      "resource_type": "channel",
      "name": "leadership",
      "acl": ["user_email:[e-mail]", "user_email:[e-mail]"]
    }
  ]
}

Or change it later, on its own, without touching anything else:

curl -X PATCH 'https://api.hydradb.com/connectors/{id}/resources/C_LEADERSHIP' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{ "acl": ["user_email:[e-mail]"] }'

This takes effect on every already-synced document from that resource, on the next query. There is no re-sync and no re-index, however many documents the resource has. Use ["__public__"] to open a resource back up.

---

4. Let connectors capture permissions for you

For supported providers, HydraDB reads the source app’s own permissions on every sync and applies them as ACLs, so you do not maintain a parallel permission model.

Provider	What is captured
Slack	Public channels are visible workspace-wide; private channels only to their members, resolved to member emails.
Google Drive	Per-file sharing: user, group, domain, and public grants. Permission-only changes (a share with no edit to the file) are picked up through the Drive changes feed, which content sync alone cannot see.
GitHub	Repository visibility. Private repos additionally capture the collaborator list when every collaborator has a visible public email; otherwise your resource rule governs.
Confluence	Space-level view permissions, with groups expanded to member emails, plus per-page view restrictions.
Jira	Who holds Browse access per project, plus per-issue security levels.

Capture is also built for other providers, including GitLab, Linear, Dropbox, Zendesk and PagerDuty, and is switched on per provider. For any other provider, set a rule per resource with acl, as described above.

If HydraDB cannot read a resource’s permissions from the provider, a resource with no rule of yours is readable by everyone until the next successful read, while a rule you set still applies. Get Connector Status reports an acl_warning on the resource meanwhile.

Precedence, when both exist:

• A per-document permission from the provider (a Drive file’s own sharing) wins over everything.
• A provider verdict of “this resource is public” will not override a rule you set. Restricting a public channel is a deliberate act, and enabling capture never widens it back.
• Otherwise the provider’s resource-level verdict wins over your rule, because the provider is the fresher source of truth.

Capture can be turned off per provider without a deploy.

---

5. Query on behalf of someone

Pass the caller’s identity as acl on POST /query (and POST /context/list, which takes the same field with the same meaning):

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what are the Q3 comp bands",
    "database": "acme_corp",
    "collection": "engineering",
    "acl": ["[e-mail]"]
  }'

A document is returned when any of these holds:

• its stored ACL is absent (unrestricted),
• it is __public__,
• its ACL contains one of the caller’s principals.

Two conveniences mean you rarely send more than an email:

• __public__ is added for you: You never have to ask for public content.
• The domain principal is derived from the email: Querying as [e-mail] automatically matches anything shared with domain:acme.com.

Send group principals explicitly when you want them: "acl": ["[e-mail]", "group:slack:C0123"].

You send	Behavior
No acl field	No filtering. Everything in scope is retrievable.
"acl": []	Same as omitting it. On a query, an empty list does not mean “nobody”.
"acl": ["*"]	Same as omitting it. Explicit “search as an administrator”.
"acl": ["[e-mail]"]	Filtered to what Grace may see.
"acl": ["__private__"]	Public and unrestricted content only.

An entry that is neither an email nor a recognized principal is kept as-is and matches nothing but public content. A typo narrows results; it never widens them. If a caller sees less than you expect, check the principal spelling first.

Access control composes with, and is independent of, metadata filters: filters express what you are looking for, ACLs express what you are allowed to find. A caller cannot widen their own visibility with a filter.

---

6. Revoking access

Change	When it takes effect
PATCH /context/{id}/metadata with a new acl	Immediately, on the next query.
PATCH /connectors/{id}/resources/{resource_id} with a new acl	Immediately, on the next query, for every document from that resource.
A permission change in the source app (channel goes private, a Drive share is removed)	On the connector’s next sync cycle.

Deleting a rule does not widen access on its own: visibility only ever widens from a value you positively set. To open a restricted resource back up, set its ACL to ["__public__"] rather than clearing it.

---

7. Common mistakes

ACLs are set but every query still returns everything

The queries are not declaring an identity. acl is opt-in per request; without it there is no filtering. Add "acl": ["<caller email>"] to the query.

A caller who should see a document sees nothing

Check the principal forms on both sides. group:slack:C0123 on the document only matches a query that declares that same group; unlike domain:, group membership is not derived from the caller’s email. Also confirm the email matches exactly: principals are compared after lowercasing and trimming, but not otherwise fuzzy-matched.

---

Related

• Connectors: syncing app data, and per-resource ACL rules
• App Sources: the ingest shape that carries acl
• Query: the acl field alongside every other retrieval parameter
• Metadata: filtering by attributes, a different question from permission
• Multi-Tenant Support: databases and collections, the isolation boundary ACLs work inside
• Update Source Metadata (API Reference): the acl replacement contract