grants operations

The exact fields each grants.* operation takes and returns.

Every op is POST /v1/<op> over HTTP and the MCP tool loom_<op>. The identity fields (org, namespace, agent, user_id, session_id) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but code.* and tracker.* (which keep their plane's), and on some ops its namespace and agent; see identities and namespaces. The operations index explains role, kind and the MCP all listing. Unknown input fields are served and named in ignored_args.

grants.approve

Approve (or reject) a pending grant request.

POST /v1/grants.approve · MCP loom_grants_approve · role admin · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
subject	str	required	Whose pending request to decide: an email or a service-account sub claim.
decision	Literal['approve', 'reject']	'approve'	approve makes the requested (or overriding) role active; reject drops the request, keeping any base role, or removes the row when the subject had no base access.
role	Literal['viewer', 'writer', 'admin'] \| None	None	Approve with a different role than was asked for (a maintainer request answered as reader).

Output field	Type	Meaning
subject	str	The subject as the request spelled it.
namespace	str	The namespace the op reads or writes.
decision	Literal['approve', 'reject']	The decision applied (echoes the request).
role	Literal['viewer', 'writer', 'admin'] \| None	The role approved (for reject, the role the request would have had); None when no grant row existed for the subject.
decided_at	datetime	When the decision was written (UTC).

grants.create

Grant another subject (user or service-account) viewer / writer / admin role on a namespace.

POST /v1/grants.create · MCP loom_grants_create · role admin · idempotent · audited

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
subject	str	required	A login handle, an email (it admits an account once that email is verified: an SSO account's or a linked one's), or a service-account sub claim.
role	Literal['viewer', 'writer', 'admin']	required	viewer, writer or admin; a code namespace takes only viewer (reader) and admin (maintainer).
granted_by	str	'admin'	Ignored under auth: the server stamps the authenticated caller.
replace	bool	False	The table replaces on (org, namespace, subject), so a create below the subject's current active role would lower it silently.

Output field	Type	Meaning
org	str	The tenant (first element of the identity tuple).
namespace	str	The namespace the op reads or writes.
subject	str	The subject as the request spelled it (the row is stored under the login handle of the account whose verified email it is, else as spelled).
role	Literal['viewer', 'writer', 'admin']	The role now active for the subject.
granted_at	datetime	When the grant row was written (UTC).

grants.list

List active grants on a namespace — who has access, at which role.

POST /v1/grants.list · MCP loom_grants_list · role viewer · read

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
limit	int	100	Rows per page, one per person, newest grant first; 1 to 500.
cursor	str \| None	None	Resume the previous page on the same namespace; unset for the first page.
fields	list[str] \| None	None	The output fields the caller reads (a whitelist resolved against the row model; an unknown name is a 422); unset, every field.

Output field	Type	Meaning
rows	list[_GrantEntry]	Live grants on the namespace, active and pending (revoked ones excluded), newest first; one row per person, their other spellings in also.
next_cursor	str \| None	Pass as cursor for the next page; None when this page is the last.
truncated	bool	True when more people follow this page (next_cursor is set).

grants.pending_for_me

Every pending request in the namespaces the caller administers, in one statement.

POST /v1/grants.pending_for_me · MCP loom_grants_pending_for_me · role viewer · read · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
limit	int	500	At most this many requests, newest first; 1 to 2,000.

Output field	Type	Meaning
rows	list[_PendingForMeEntry]	Pending join or elevation requests in namespaces the caller administers, newest first; empty for an anonymous caller.

grants.revoke

Remove a subject's grant on a namespace.

POST /v1/grants.revoke · MCP loom_grants_revoke · role admin · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The namespace the op reads or writes.
subject	str	required	Whose grant to revoke: a login handle, an email or a service-account sub; the person's row under each verified spelling goes, and a pending request is rejected.

Output field	Type	Meaning
revoked	bool	True when any of the subject's grant rows was found and revoked; false when it had none.
revoked_at	datetime \| None	When the revoke was written (UTC); None when nothing was revoked.

grants.share_agent

Let another agent of the caller's trust read, or write, the caller's own namespace.

POST /v1/grants.share_agent · MCP loom_grants_share_agent · role writer · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The calling agent's own namespace, the only one it may share.
grantee	str	required	The agent of the same trust to share it with, as its control plane names it.
role	Literal['viewer', 'writer']	'viewer'	What that agent may do there: viewer reads, writer also writes.

Output field	Type	Meaning
namespace	str	The namespace the op reads or writes.
subject	str	The subject the grant is stored under, sa:<trust>:<agent>.
role	Literal['viewer', 'writer']	The role now active for that agent.
granted_at	datetime	When the grant row was written (UTC).

grants.unshare_agent

Take back what the caller lent another agent of its trust.

POST /v1/grants.unshare_agent · MCP loom_grants_unshare_agent · role writer · idempotent · audited · not listed under the MCP all toolset

Input field	Type	Default	Meaning
org	str	required	The tenant (first element of the identity tuple).
namespace	str	required	The calling agent's own namespace.
grantee	str	required	The agent of the same trust whose grant there to revoke.

Output field	Type	Meaning
revoked	bool	True when the agent held a grant and it was revoked.
revoked_at	datetime \| None	When the revoke was written (UTC); None when nothing was revoked.