Approvals: who decides, and how Bucker knows it was a person
When policy holds an action for a human, an approval request opens. This page is about the
decision: where it is made, what proves the person was there, and what a rejection must say. The
rules about who may decide (human-only, fix:approve, the sole-approver rule) are in
agent governance; the rules about what is held are the approval
policies in Settings.
The decision page
Every request has one page where it is decided:
/org/<orgSlug>/approvals/<requestId>
That address carries the organization slug and the request id and nothing else: no token, no
personal data, no decision verb. It is the only decision link a notice, a Slack message, an e-mail,
a push or an MCP decisionUrl ever carries, and it is a pointer to a place, never a credential.
- It needs your own session. Opening it signed out is the ordinary sign-in redirect back to the same address. Nothing about the page is pre-authenticated, so a link pasted into a channel or handed to an agent cannot be used by whoever holds it.
- It is resolved for the person who opened it.
GET /orgs/:org/approval-requests/:id/decision-pagereturns the request, a digest of the plan, the plan as the requester wrote it, the delegation chain, the policy that held it, your own progress, what a vote will ask of you, and whether you can decide with the reason if you cannot. - An opener inside the delegation chain sees the rule, never a button. If you started the run, or you are the person an agent acts for, the page says that the initiator of a run cannot be its sole approver and names who has to decide it. The vote is refused again on the server; the page is the explanation, not the control.
- Everything an agent wrote is text. The plan and the names are shown as plain text: no Markdown, no links, no images, bidirectional and invisible characters removed, at most 4,000 characters.
- A request in another organization, or in a project you cannot read, is a 404, the same as one that does not exist.
The decision card
Every request that is held for a person carries a decision card, built by the server when the
request is filed and stored on the request (payload.card, at most 2,000 tokens and 32 KB). It is
the same document on every channel: the decision page, the inbox, the Slack message, the e-mail, a
push, and an MCP client that draws cards or reads six plain lines.
| Section | What it says | Does it change? |
|---|---|---|
plan |
The change as before and after, the plan text, and the digest a vote is bound to | Never. It is what the request was filed with |
target |
The kind, the id and the version of the object the plan was made against | Never |
effect |
The blast radius (each unmeasured field named, never shown as zero), how to undo it, how long it lasts, and the signal that verifies it | Never |
spend, chain, policy |
The cost effect and incident spend so far, who asked and for whom, and why the request exists | Never |
context |
The issue, the trace, how many sessions, the flag and variant, and the release the request's keys join to | Re-read on the decision page, and stamped with when |
So a decision page opened tomorrow still shows the plan, the target version and the digest the
request was filed with, even if the target has moved since; only context is fresh, and the page says
when it was read. The inbox shows the copy taken when the request was filed.
Every value that came from outside Bucker (your telemetry, the requester's words, an id a caller
chose) is listed in the card's untrustedFields and shown as text. Links and images are removed
from those values and URL schemes are broken (https[://]host), so nothing in a card can be
clicked or fetched; you can still read where a plan would send data. A join across organizations
is never made: an issue, flag or alert rule from another organization named in a request is simply
not found.
Per channel:
- Slack shows the effect and the digest, never the context. A request that needs a security key (CRITICAL, or dual control) says needs step-up: open in Bucker and offers no button, whether or not the request has a card (a request whose card could not be built is still CRITICAL).
- MCP Apps (
ui://bucker/decision-card) draws the card read-only with one action, which opens the decision page. There is no Approve or Reject in the view and no in-band vote. - No cards (a client that cannot draw them) gets six lines: what is asked, what a yes does, who must decide, when it lapses, the decision page, and that nothing has been done yet.
approvals_list(MCP, read-only) lists your own pending and recent requests with their status, expiry and, for a rejected one, its reason code.queuePositionis always null until batching ships.- Webhooks send
approval.requestedandapproval.decidedwith the request id, action, status and expiry only (see outbound webhooks).
The inbox lists requests and still decides the simple ones in place. A CRITICAL request is decided on the page only, approve and reject alike (the inbox links to it), because only the page can collect a security-key confirmation. A request that needs dual control is known to the server; an in-place vote on one is refused with the same link.
Step-up: proof that you are here, for this plan
A session says how you began a sitting, perhaps days ago. For a request that is worth more than a cookie, a vote needs a fresh confirmation tied to the decision itself.
When a vote needs one (approving or rejecting):
- the request is CRITICAL, or
- the request needs dual control, from either side: the policy that held it froze
minApproversof 2 or more, or its action is dual-control in the registry and the action'sdualControlWhencondition holds (an unmeasured input counts as holding).
Each vote on such a request needs its own confirmation, not only the last. A rejection is included on purpose: on these requests one "no" ends the request, so a veto cast from a stolen session would deny the change the incident is waiting on.
What the confirmation is. Deciding asks your security key or passkey to sign a challenge that is
sha256(requestId ‖ planDigest ‖ serverNonce):
| Property | Meaning |
|---|---|
| Bound to the request | An answer made for one request is refused on another. |
| Bound to the plan | The server recomputes the digest from the request at vote time. A plan that changed after the prompt was drawn no longer verifies. |
| Single use | The challenge is spent by the first attempt, right or wrong. |
| Five minutes | It expires. The page asks for a challenge at the moment of the vote, not at load. |
| Charged | Every attempt counts against the account's MFA attempt budget, and a failure is a MFA_CHALLENGE_FAILED security event with path approval_vote. |
The challenge comes from POST /orgs/:org/approval-requests/:id/step-up/challenge, or from the
session step-up door POST /auth/mfa/webauthn/step-up/options with a body naming the request. It is
a separate purpose from the session step-up, so a challenge minted for one can never be spent on the
other.
TOTP is the narrow fallback. A six-digit code is accepted only when you have no registered key and your organization does not require a phishing-resistant factor. A code cannot be tied to the plan, so the receipt records which method was used.
What is recorded. ApprovalVote.stepUp holds { method, digest, at }: the method
(security_key, passkey or totp), the plan digest the proof was bound to, and when. Never a
secret, an assertion or the nonce. The vote's channel and the request's decisionChannel record
where it was cast.
When it is not enough or not possible. A vote without a valid confirmation is a 403 with
details.refusalCode: "STEP_UP_REQUIRED", a stepUp reason (missing, invalid,
method_not_allowed) and a remedy naming the enrolment page and the decision page. The refusal is
audited as approval.step_up.refused with the channel and session. On a request that needs no
confirmation, one that is offered with a vote is still verified and recorded, and refused if it does
not verify.
Channels that cannot carry a WebAuthn assertion cannot satisfy it, whatever they send: Slack, mobile push, chat and e-mail. A Slack Approve, or a rejection from Slack's reason menu, on a request that needs a confirmation records no vote and answers with the decision-page link. The same holds for the MCP surface: no tool decides.
Rejections that teach
A rejection needs two things:
- a
reasonCodefrom the closed listwrong_target,too_wide,not_needed,unsafe,evidence_insufficient,duplicate,stale,other, and - words (
reasonText) of at least 10 characters saying what the next proposal should do differently.
Without either it is a 400 and the request stays open. The code lands on the request
(reasonCode, with the words in reason) and in the metadata of the approval.reject audit row, beside the
channel and the session. Codes are labels for whatever raised the request. Slack's reason menu files
under the same list; a bare Slack Reject records nothing and points at the menu or the page.
Where the decision is audited
| Row | When | Notes |
|---|---|---|
approval.approve |
each approving vote | channel, sessionId, stepUpRequired, stepUpMethod in the metadata |
approval.reject |
a rejection | reasonCode, channel, sessionId, stepUpRequired, stepUpMethod in the metadata |
approval.step_up.refused |
a vote turned away for want of a valid confirmation | why, channel, sessionId |
sessionId is the identifier of the access token behind the vote: attribution, never the token.