Permissions

Reader retrieves. Contributor also loads and removes documents. Manager also grants access and deletes the base. Owners and admins of the organisation manage every base without needing a grant.

Three levels rather than a policy engine, because every request anyone has actually made is one of those three. Grants are revoked rather than deleted, so the record still says who had access, who gave it to them and when it stopped.

An unscoped key reads nothing. Not everything. There is no default knowledge base, and inventing one would mean a key created for one purpose quietly reading every document the organisation has ever uploaded.

A key bound to a person is the intersection. If the key is scoped to three bases and that person holds one, it reads one. Revoke the person and the key stops on the very next request, with nothing to redeploy and no cache to expire. If they leave the organisation, the key falls to nothing rather than back to its own scope.

A key cannot write. Whatever it is scoped to, no API key can load a document. An agent that could both read a base and write to it closes the loop on itself: it reads a planted instruction and complies by writing more.

Per-document permissions sound finer grained and behave worse. Retrieval is a top-k over an index, so either you filter after the search, in which case a narrowly permissioned reader silently gets worse answers rather than fewer results, or you push the permission into the index, in which case every access change is a re-index.

Per base is a plain filter on one column: cheap, accurate, and a rule a person can read out loud in an access review. If you need a split, make a second base.

We do not mirror your source system's permissions. Syncing a document store and keeping its ACLs in step is a different product and we would rather say so than half-do it.

Naming a base you cannot read answers 404, never 403. A "forbidden" would confirm that a base with that handle exists and that somebody else can read it, which across organisations is an enumeration oracle sitting in an error message. From where you stand, it does not exist.