Approval expiry, exact action and the Stop switch
An approval lasts 30 minutes, is bound to the exact action it was given for, and any agent can be stopped on its own. Each step is a signed receipt.
On this page
Three rules make an approval mean what a person thinks it means.
An approval lasts 30 minutes#
An approval is valid for 1800 seconds by default. Set another lifetime with VERDOCK_APPROVAL_TTL_SECONDS (60 to 604800) in the workspace, or default_ttl_seconds and ttl_seconds in verdock_core. The clock is checked when the approval is used, not only when it is given. An approval that ran out of time is invalid: the action goes back to held with the reason Approval expired. Approve again. and the hold is a signed receipt. Approving again opens a fresh 30 minutes.
An approval is for one exact action#
Every approval carries a hash: SHA256 over canonical JSON of the operation, the target, amount_minor, the currency, the counterparty and any other material field. The approver signs the request that contains the hash. If an approval for 499 is used for 4,999, it is refused with Approval does not match this action: amount changed. A changed target or currency is named the same way. The action is blocked and the refusal is a signed receipt. The unchanged action passes.
approval_id = store.request("payout", "payout", "supplier-1", 499, "USD", None, "payout-agent")
store.approve(approval_id, "anita")
store.require(approval_id, "payout", "supplier-1", 4999, "USD")
# Refused: Approval does not match this action: amount changedStop one agent#
Stopping an agent holds every new action from that agent with the reason Agent stopped by <role>. Start the agent to release. Each hold is a signed receipt. Other agents keep running. An action that is already running finishes and is checked. Stop and start are receipts with who did it and when. Starting the agent releases its held actions, and each one goes through limits, approvals and credits again.
In the workspace, owners and admins stop and start an agent from the Agents page or Monitor, or through the API:
| Call | What it does |
|---|---|
POST /v1/workspaces/{id}/agents/{agent}/stop | Stops the agent. |
POST /v1/workspaces/{id}/agents/{agent}/start | Starts the agent and releases its held actions. |
GET /v1/workspaces/{id}/approvals | approvals for the cards and log for the approval log. |
POST /v1/workspaces/{id}/approvals/{approval}/approve | Approve. Send {"execute": {"amount_minor": 4999}} to check the approval against the exact action about to run. |
The approval log#
The Approvals page lists every approval with the requester, the approver, the time and the method, and exports the table as CSV. The method is key (an approver signature), code (a one time code) or session (an approver signed in to the workspace). The log is read from the approvals table and the signed receipts. Nothing is kept for it separately.
Review rules#
Three switches in the saved policy document make an approval a review. They are off until you turn them on:
{"policy": {}, "team_cap_minor": 0, "approval_rules": {"require_reason": true, "require_review": true, "require_step_up": true}}- Bands. The policy decides how many approvers an amount needs: within limits runs, above
approval_above_minorneeds one checker, above anapproval_bandsthreshold needs two approvers. The people on a request show by role: Requester, Checker, and Approver 2 (Finance Controller). - The requester cannot approve. The person who raised a request sees "You raised this request" and cannot decide it. One person counts once.
- Reason code.
require_reasonasks for a code from a fixed list (for exampleDUPLICATE_CHARGEorCUSTOMER_REQUEST) and a note. A rejection needs a note. - Review first. The approver opens the request, sees it with the earlier payments to the same counterparty, and then decides. The time to decide is measured. A decision made in under 5 seconds is flagged. Monitor shows the mean and longest review and how many were flagged.
- One time code.
require_step_upasks for a 6 digit code from an authenticator app before the decision is recorded. A code works once. Five wrong codes lock the approver until an admin resets it withPOST /v1/workspaces/{id}/approvals/step-up/reset. Set up your code withPOST /v1/workspaces/{id}/approvals/step-up. - Evidence. Each approval in the log carries the approver, the time, the fingerprint of the key that signed the receipt and the receipt hash.
- No batch.
POST /v1/workspaces/{id}/approvals/batchis refused:Each approval is reviewed one at a time.