App grants — create, list, revoke, withdraw¶
An App grant lets one worker, or one agent installed in an App, do one registered action with the exact values you name, for as long as the grant allows. This page is the lookup for the four calls a person who manages the App (and, for some of them, a worker) can make, the refusals each returns, and the one MCP tool.
Not the organization grant
This is a different thing from the organization
individual grant that adds an action
to a member's role, and from the hadron grant CLI group, which manages
that older kind. The CLI's hadron grant revoke calls the older
RevokePrincipalGrant operation, not revokeGrant below. Nothing in the
CLI or the portal manages App grants yet, so this page covers GraphQL and
MCP only.
Only where signing is switched on
The manager arm of createGrant and the hadron_create_grant tool exist
only on a deployment where PASSKEY_SIGNING_ENABLED is on. The deployment
controls this; do not assume the call is present. Your host's tool list shows
whether the MCP tool is there.
A new grant is pending until a person signs it¶
A grant made by any of the calls below is born pending and allows nothing. Only a person's signature activates it. Nothing on this page activates a grant, and a worker can never sign. How a grant is signed is outside this page.
The API gives a grant no state field. To judge one, read:
allows— whether it allows its action right now. It is a fact about this instant, judged on the database clock: activated, not revoked, holder still there, started, not expired, not spent.- the timestamps:
createdAt,activatedAt,startsAt,expiresAt,revokedAtandholderDepartedAt.
Use "pending", "active", "spent", "expired" and "revoked" as plain descriptions
of those facts. A grant that was withdrawn, or whose holder went away, is
simply ended. A withdrawal writes the same end stamp (revokedAt) and the
same REVOKE event as a revocation, so you cannot tell the two apart by a
state.
The first end of a grant stands. Revoking or withdrawing a grant that has already ended returns it as it is, with no second stamp and no second event.
Who may do what¶
| Call | Who may call it | Result |
|---|---|---|
createGrant with input.appRef |
A person who manages the App, acting as themselves. | A new pending grant. The row records the person as requester, never a worker. |
appGrants(appRef, limit, offset) |
The same person. | Every grant of the App, in every condition, newest first. |
revokeGrant(ref, instruction) |
The grant's issuer (while still a member of the App's organization), whoever manages the App, or a held worker on a validated instruction from a holder who may. | The grant, ended now. Immediate and unsigned. |
withdrawGrant(ref) |
Only the recorded requester — a person, or the worker session that asked — and only while the grant is pending. | The grant, ended. |
A bound worker session can also ask for a grant for itself or its role agent
with createGrant (no appRef). That is the worker's route and is covered
with the signing flow, not here.
Who "manages the App" is the same audience that lists and mints App keys.
Create¶
createGrant(input: CreateGrantInput!), with input.appRef naming the App.
A manager may name as holder a worker of the App or an agent installed in
it, and no one else.
| Field | Meaning |
|---|---|
appRef |
The App, by id or URN. You must manage it. |
action |
A registered action's dotted name, such as schedule.create. |
values |
Exactly the action's declared parameters. Each is a string or a list of at most 100 distinct strings, as an id, never a URN. Any other key or shape is refused. Never put a secret here. |
holderKind |
WORKER or AGENT. |
holderRef |
The holder's id, not a URN. |
startsAt, expiresAt |
Optional. Not usable before or after; expiresAt must follow startsAt. |
maxUses |
Optional. A positive integer; at most this many uses once signed. |
reason |
Why you ask, at most 2,000 characters. The signer sees it labelled as the requester's words. |
List¶
appGrants shows the whole record, including revokedByUserId,
holderDepartedAt and each signature's signer and passkey label, never a
credential id or public key. It pages: 20 rows by default, at most 200;
limit: 0 returns only the count.
An empty page does not mean the App has no grants. Anyone who is not a
person managing the App (a member who does not manage, an outsider, a worker
session, an App key, a run, an impersonated session) and an unknown App all get
an empty page, never an error. revokedByUserId and holderDepartedAt are
read only through appGrants; they are null on grant, grants and
myGrants.
Revoke and withdraw¶
revokeGrant ends a grant that has not ended yet, pending or active. A worker
revokes only on an instruction from a holder who may; see Acting on a holder's
instruction.
withdrawGrant is the requester taking back an ask before it is signed. A
withdrawal that loses the race to the signature is refused. A worker
requester's withdrawal records the person driving it as revokedByUserId.
Refusals¶
Each refusal happens before any write and never names a value you submitted.
| Call | Code | When |
|---|---|---|
createGrant |
GRANT_NOT_MANAGER |
The caller is not a person who manages the App. An unknown App gives the same answer. |
createGrant |
GRANT_HOLDER_NOT_ALLOWED |
Any holder other than a worker of the App or an agent installed in it. |
createGrant |
GRANT_ACTION_UNKNOWN |
The action is not registered. |
createGrant |
GRANT_VALUES_INVALID |
A value that does not match the action's declared parameters, an undeclared key, or a list above 100 entries per parameter. |
createGrant |
GRANT_TERMS_INVALID |
The terms are invalid, including a reason above 2,000 characters. |
revokeGrant |
GRANT_NOT_MANAGER |
Not allowed. A grant that does not exist or that you cannot see gives the same answer. |
withdrawGrant |
GRANT_NOT_FOUND |
Unknown and unreadable alike. |
withdrawGrant |
GRANT_NOT_REQUESTER |
You are not the recorded requester. |
withdrawGrant |
GRANT_NOT_PENDING |
The grant has been activated. |
Current behavior that no rule promises¶
These are how the server behaves today. Do not build on them as guarantees.
- The issuer may revoke only while still a member of the App's organization.
- Revoking or withdrawing a grant that has already ended returns it unchanged, as a success.
- A manager may name only a worker or an installed agent as holder.
- A worker's withdrawal records the driving person as
revokedByUserId.
The MCP create tool¶
hadron_create_grant is the manager's createGrant over MCP. It calls the same
code, so the gate, the holder rules and the refusals are one. It is listed with
the other tools under App grants.
Listing, revoking and withdrawing are not available over MCP; use GraphQL.
Related¶
- Authorization — roles, grants, guardrails — the organization role and grant model this page sits beside.
- Authorization — the same model in plain language.
- Acting on a holder's instruction — how a held worker revokes on a person's say-so.
- MCP tools — every
hadron_*tool.