Skip to content

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, revokedAt and holderDepartedAt.

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.