Single-use confirmations
Since 2.3.0. A confirmation is the smallest approval there is: one named person confirms one exact action, once, before it expires. The action is identified by a payload hash your app computes — for an AI agent’s tool call, a hash of the tool name and its arguments — so the person confirms that call, not a later one with different arguments.
It is opt-in and lives in its own table (approval_confirmations, migration 0009). Nothing about approval rounds — status(), progress(), approvals:expire, the round events — changes when you use it:
| Guarantee | How |
|---|---|
| Only the named person | confirm() and decline() compare the answering model’s morph type and key with the stored person. A delegate, an approver of the subject or a model of another type with the same id is refused (not_the_person). |
| Only the exact action | The hash given to confirm() must equal the stored one, compared in constant time (hash_equals). Anything else is refused (mismatch) and the confirmation stays pending. |
| Once | The first confirm or decline moves the row out of pending with one conditional UPDATE … WHERE status = 'pending' AND (expires_at IS NULL OR expires_at > now). Of two concurrent answers exactly one matches; the other is refused (used / declined). |
| Before it expires | An overdue confirmation reads as expired at once (isExpired(), effectiveStatus(), the pending scopes), is refused (expired), and is finalised by the sweep or by the refused answer. |
Asking for a confirmation
use Carbon\CarbonInterval;
use RoundlyConsulting\Approvals\Facades\Approvals;
$hash = hash('sha256', json_encode([$toolName, $arguments], JSON_THROW_ON_ERROR));
$confirmation = Approvals::confirmation($toolCall) // the subject: any saved model
->payload($hash) // required
->by($user) // required: the one person who may answer
->singleUse() // optional marker, see below
->expiresIn(CarbonInterval::minutes(5)) // or ->expiresIn(300) / ->expiringAt($moment)
->request(); // ApprovalConfirmation, status pending| Method | Returns | Purpose |
|---|---|---|
payload(string $hash) | self | The hash of the exact action to confirm. Required. |
by(Model $person) | self | The one person who may confirm or decline. Required. |
singleUse() | self | A marker: every confirmation is single use, so it changes nothing. |
expiresIn(DateInterval|int $interval) | self | Expire this long from now (a CarbonInterval, or seconds). |
expiringAt(CarbonInterface $at) | self | Expire at this moment. |
request() | ApprovalConfirmation | Store it pending and fire ApprovalConfirmationRequested. Without an expiry, confirmations.expiry applies. Throws InvalidConfirmationException. |
request() stores the row and fires ApprovalConfirmationRequested. It throws InvalidConfirmationException, storing nothing, when by() or payload() is missing, the subject or the person is not saved, the hash is blank or longer than 255 characters, or the expiry is not in the future. Without expiresIn() / expiringAt() the confirmation expires approvals.confirmations.expiry seconds from now (default 900, 15 minutes; env APPROVALS_CONFIRMATION_EXPIRY); set it to null and such confirmations never expire.
singleUse() is a marker, not a switch. Every confirmation is single use; there is no multi-use mode. A confirmation that could be used again would be a standing permission (“let the agent run this tool for the next hour”) — a different thing with different risks, and it would make the payload binding meaningless for a repeated call. singleUse() exists so the call site says what it relies on.
The hash is stored as given (payload_hash, up to 255 characters) and is in the model’s $hidden, so toArray() and JSON never render it. Compute it the same way on both sides — canonicalise the arguments (key order, whitespace) before hashing.
Confirming
use RoundlyConsulting\Approvals\Exceptions\ConfirmationRefusedException;
try {
Approvals::confirm($confirmation, $request->user(), $hashOfTheCallAboutToRun);
// run the tool
} catch (ConfirmationRefusedException $refused) {
return response()->json([
'code' => $refused->errorCode(), // mismatch | used | expired | not_the_person | declined
'message' => $refused->getMessage(), // translated (en, sk)
], 409);
}confirm(ApprovalConfirmation $confirmation, Model $person, string $hash) reads the row first — the instance you pass is refreshed, so a stale copy is fine — then checks in this order:
- $person is the named person — else not_the_person. Checked first, so a stranger learns nothing else about the confirmation.
- The confirmation is still open — else used (confirmed already), declined, or expired (past its expiry; an unswept one lapses now and ApprovalConfirmationExpired fires).
- The hash matches — else mismatch; the confirmation stays pending, so the right call can still be confirmed.
- The atomic claim. Losing it to a concurrent answer, or to the sweep, refuses with what moved the row: used, declined or expired.
On success the row is confirmed, resolved_at is set and ApprovalConfirmationConfirmed fires. The claim runs in a transaction of its own, retried on a serialization failure, so under repeatable read or serializable the losing session is refused with used instead of a database error. Inside a transaction of yours it is a savepoint and is not retried — a serialization failure there reaches your transaction, as it would for any other write in it.
Declining
Approvals::decline($confirmation, $user, 'Not on the production repository');decline(ApprovalConfirmation $confirmation, Model $person, ?string $reason = null) takes no hash. Only the named person can decline, and only while it is pending and unexpired (not_the_person, used, declined or expired otherwise). Declining uses the confirmation up the same atomic way, so a confirm and a decline racing each other cannot both succeed. The reason is stored in reason, resolved_at is set and ApprovalConfirmationDeclined fires.
Refusals
ConfirmationRefusedException (extends ApprovalsException) carries $refusal (a ConfirmationRefusal), errorCode() (its value), $confirmation and a translated getMessage() from approvals::confirmations.refused.<code>, in English and Slovak:
| Code | ConfirmationRefusal | English message | Raised by |
|---|---|---|---|
mismatch | Mismatch | This confirmation was given for a different action. | confirm() |
used | Used | This confirmation has already been used. | confirm(), decline() |
expired | Expired | This confirmation has expired. | confirm(), decline() |
not_the_person | NotThePerson | Only the person this confirmation was requested from can answer it. | confirm(), decline() |
declined | Declined | This confirmation has already been declined. | confirm(), decline() |
ConfirmationRefusal::message() returns the same text in the current locale. Publish the translations with --tag=approvals-translations to reword them.
Listing
Approvals::pendingConfirmationsFor($user)->latest()->get(); // waiting on this person
Approvals::confirmationsFor($toolCall)->get(); // every one about the subject
Approvals::confirmationsFor($toolCall)->pending()->exists(); // any still open?Both return an Eloquent Builder of the configured model. Pending means status pending and not past its expiry, so an overdue confirmation drops out of the list before the sweep runs. The same scopes are on the model: pendingFor($person), forSubject($subject), pending(?$moment) and overdue(?$moment).
The expiry sweep
Approvals::expireConfirmations(); // now, every subject type
Approvals::expireConfirmations(now(), ToolCall::class); // one subject type (class or morph alias)php artisan approvals:expire-confirmations
# Expired 3 confirmation(s).Schedule the command like approvals:expire:
use Illuminate\Support\Facades\Schedule;
Schedule::command('approvals:expire-confirmations')->everyFiveMinutes();Each overdue pending confirmation moves to expired with a conditional write, and ApprovalConfirmationExpired fires once per confirmation; one answered while the sweep runs keeps its answer. approvals:expire does not touch confirmations, so a host that never published migration 0009 can keep running it. The sweep is for the event and for tidy rows — correctness does not depend on it, since an overdue confirmation is already refused and already left out of the pending lists.
What does not apply
- The authorization gate and exclusions — approvals.authorization and approvals.exclusions gate approval decisions. A confirmation names its person explicitly, and that person is usually the author of what is being confirmed, so neither applies.
- Delegation — nobody can confirm on the person’s behalf.
- Subject fingerprints — the payload hash is the binding.
Facade, DI and actions
// Facade
Approvals::confirm($confirmation, $user, $hash);
// Injected manager — the same API
public function __construct(private ApprovalsManager $approvals) {}
$this->approvals->confirm($confirmation, $user, $hash);
// Raw actions
app(RequestConfirmationAction::class)->execute($subject, $person, $hash, $expiresAt);
app(ConfirmAction::class)->execute($confirmation, $person, $hash);
app(DeclineAction::class)->execute($confirmation, $person, $reason);
app(ExpireConfirmationsAction::class)->execute($now, $subjectType);Model and table
ApprovalConfirmation (config approvals.confirmation_model, swappable; it must extend the package’s model) lives in approval_confirmations — see Models & schema. Relations subject() and person() (morph-to); helpers isPending(?$moment), isOverdue(?$moment), isExpired(?$moment), effectiveStatus(?$moment), isAddressedTo($person), isFor($subject) and matchesPayload($hash). The table has no soft deletes — the status column is its history — so prune old rows yourself (Prunable) if you need to; a confirmation deleted while someone answers it throws ModelNotFoundException.
Testing
Approvals::fake() records RequestConfirmation, Confirm, Decline and ExpireConfirmations operations — a refused confirm is not recorded:
$fake = Approvals::fake();
// … exercise the code under test …
$fake->assertConfirmationRequested($toolCall, $user);
$fake->assertConfirmed($toolCall, $user);
$fake->assertNothingDeclined();
$fake->assertConfirmationsExpired(1);ApprovalConfirmation::factory() builds the configured model, with about($subject), askedOf($person) and overdue() states.
Show your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.