Goal: by the end of this lesson you can read the Grants panel, add and revoke a grant, and predict which editor operations a given user can perform — because you’ll know the seven capabilities, how namespace scope works, and where the checks actually fire.
Concepts introduced: the :grant entity, the capability
vocabulary, capability implication, namespace-scoped
authorization, default-deny, personal namespaces.
A grant is a row: subject (a member’s email, stored as their stable account id) + capability +
namespace. Authorization is default-deny: an operation is
allowed iff some grant covers it. “Covers” is generous in two
directions — a grant on a parent namespace covers all its
descendants (a grant on acme covers acme.billing.invoices;
a blank namespace is a root grant covering everything), and
some capabilities imply others.
The closed vocabulary (anything else is rejected at create time with a 400):
| Capability | Lets the subject… |
|---|---|
read |
discover a fn + see its SIGNATURE (slots, types, return) |
view-impl |
see a fn’s INTERNAL COMPOSITION (parent chain + bindings) — withhold it and the fn stays executable but its impl is hidden |
write |
create / move / edit fns there — and run them |
execute |
run fns there (and nothing else) |
admin |
everything above, within the scope |
bind-args |
edit only a binding’s VALUE (not structure) |
append-list |
append items to list-typed bindings |
Implication: admin implies all of them; write implies
execute (a writer can run what they may edit — which is why
the org-wide write a new member gets in Lesson 27 is a working
membership), view-impl (you can’t edit a fn you can’t see) and
the two narrow edit caps (bind-args, append-list). execute
on its own is a run-only grant. The narrow caps exist so you can
hand someone “tune the parameters of my app” without handing them
“restructure my app”.
One freebie needs no grant row at all: every user implicitly
holds admin over their personal namespace
(<prefix>.<account-id> — built from the stable id, so it survives an email change).
Three enforcement layers read the same grant table:
write there (a fn created outside any namespace needs a
root grant — blank namespace); a value-only binding edit passes
with bind-args; appending a list item with append-list.
Namespaces are gated too: creating, renaming, moving or deleting
one needs write on its parent namespace — on both the old
and the new parent for a move — so a grant on acme.team cannot
pull acme.secrets under it. Rotating a secret’s value needs
write on the namespace of the fn that holds it.execute on its
namespace (a write grant there counts)./api/execute requires execute (or a write).The editor also reads the grant table indirectly: the
X-Graphden-Capabilities header (Lesson 27) that unlocks
tenant-mode UI is computed from these same rows.
You can read your own answer without opening any admin panel: avatar → Settings → Access lists the capabilities you hold in this org, under a tenancy addon — the same fact every response carries in that header. It is a readout, not a control: who may touch what is enforced by the server, and the admin panels stay on the Organization surface.
Expand Grants on the Organization surface (open it from the
account menu; same gating as Members: signed in + tenancy addon). The partial (GET /partials/grants-admin)
renders:
Subject | Capability | Namespace |
alice | write | acme.billing | ×
bob | execute | acme | ×
Below it, the add form: a subject input (a member’s email, or a
role name — see below; with type-ahead over the org’s members),
a capability <select> (the seven, plus the require-2fa policy
below), a namespace input, and
+ Add grant
(POST /api/grants).
One subtlety worth knowing: the form takes an email, but enforcement keys on the account’s stable id — the create handler resolves the email to that id at write time and stores only the id (the email is re-joined from the account row for display). Typo the email and you get a “dead” grant that matches no one — its subject cell renders the raw id — but it doesn’t throw.
A team as the subject. Type the name of one of the org’s roles
(Lesson 29) instead of an email and the grant is
stored with subject-kind role: everyone who is a member of that
role holds it, and adding someone to the role (or removing them) is
the only thing you edit later. That is how two teams sharing one
org keep their namespaces apart — backend gets admin on
svc-a, frontend gets admin on svc-b, and the contract
namespace both read stays under whichever team owns it. The row
shows the role’s name in the subject cell. Resolution order for a
typed subject: a known member’s email → a role name → a pending
email (a dormant grant, claimed on first sign-in).
One special capability rides the same rows: require-2fa, the
policy group of the <select>. Granted to a member from the
panel (or, through the API with subject-kind org, to the whole
org) it doesn’t allow anything — it requires the subject to
enroll two-factor authentication before any other request passes
(Lesson 36 shows enrollment). It
implies nothing and nothing implies it.
Revoke is the row’s × (confirm: “Delete this grant?”) —
this one goes through the generic entity endpoint
(DELETE /api/entities/grant/:id), and the row just drops out
of the table.
Grants are org-scoped RBAC, administered from WITHIN the org —
not by the platform operator. The Grants panel mounts, and its
create / revoke endpoints authorize, only for a user who may hand
out grants in their own org: the org owner, or a holder of the
manage-grants org-management capability. Every other member sees
no panel. (The operator, on the public platform org, holds no
manage-grants and does not administer a tenant’s grants.) Tenants
are both the subjects AND the administrators of grants within
their org.
Handing several members the same org-management capability as one row is a role — the next lesson, Lesson 29.
(An org owner — or a manage-grants holder — on a tenancy-addon
instance.)
carol to your org acme (Lesson 27). In Grants, remove the
org-wide write grant that invitation supplied, and ensure no role or
other broader grant supplies write or admin over acme.settings.
Use a namespace outside carol’s personal namespace: its implicit admin
permission would also invalidate this narrow-access exercise.carol / bind-args / acme.settings. As
carol: editing a binding VALUE under acme.settings works;
renaming the fn or changing its parent is denied — that needs
write.write on acme — now structural edits pass
anywhere under acme, including acme.settings (parent-path
coverage).can? composes implication + scope — the pure
decision function and its default-deny shape
(graphden.tenancy.grant, in the private graphden-tenancy repo).lesson 29 — Roles: capabilities as a bundle.