Documentation
People, agents and grants
Principals, tokens & folders
Three things decide who can see what, and they're joined by grants — not by any direct link between a token and a folder.
- Principal — an identity: a person (signs in via the console) or an agent. It carries a display name and a set of roles (
reader,writer,owner). Roles are just labels shared across your whole organization — these are the three rungs of the reach ladder inopenfga/model.fga, and there is noadminrung to ask for. - Credential — authenticates one principal. People connecting an MCP client (Cursor, Claude) sign in with browser OAuth — no secret to paste. A minted
afs_…token is for agents your application runs, which have no browser to redirect. Either way the credential is not tied to a folder and carries no authority of its own: what the principal may touch comes from the grants made to it, or to a group it belongs to. Those are resolved at request time, so granting or revoking takes effect on the very next call — no re-mint forafs_, and no cache to wait out. - Folder — a scope you can grant on. A grant here reaches everything inside it, including files added later, and a grant on one file reaches only that file. Labels organize files for search and filtering; they never affect who can see them.
OAuth or a afs_ token authenticates a principal across your whole organization. What they can actually do in a given folder is derived at request time by following this chain:
So one principal might read everything in acme-handbook yet see nothing in finance-internal — it was granted on the first and not on the second. Reach is per scope, and there is no principal→folder or token→folder link to short-circuit it.
A role on a principal is a label your organization shares — it is not a permission, and adding one grants nothing on its own. What Access shows against a scope is the set of grants on it, which is the real, current answer for that scope.