Skip to Content
Documentation menu

Guides

Human review

When a request escalates, it waits for people you name. Their votes are signed, sealed into the audit chain, and only ever cast by a person: never by an API key.

Approvers

Add approvers under Dashboard → Govern → Approvers, each with a role. An approver can vote two ways:

  • From an email. When a request escalates, approvers whose role can approve that agent are emailed approve and reject links. Each link works once, only for the person it was sent to, and expires after 72 hours.
  • From the dashboard. Link the approver to the login they sign in with (only the account owner can do this). They then vote under Monitor → Requests, with MFA if your team requires it.

Quorum and roles

Set per agent:

SettingEffect
human_approver_quorumHow many distinct approvals a request needs (default 1).
human_approver_role_requirementsWhich roles may approve. Rejecting is never restricted by role.
requires_human_approval_overrideSend every in-scope request from this agent to review, even ones policy would allow.

One rejection ends the request. Approvals count until the quorum is met. Nobody can vote twice, and a request already decided (by another approver or by the person the agent acts for) can't be changed.

Deadlines

Escalations carry an SLA (escalationSlaMinutes). Approvers get a warning before it runs out and a breach email after. Under Dashboard → Govern → Policies you choose what a breach does: notify (the default: it stays pending) or deny (it is rejected and the agent's request denied, failing closed).

Getting the result in your backend

The agent got escalate and an approvalRequestId. To learn when it's decided:

  • Webhook (recommended). Subscribe to authorization_approval_granted, authorization_approval_rejected and authorization_approval_expired. See Webhooks.
  • Poll. With your account key:
GET/api/v2/approval-requests/:idaccount key
bash
curl https://www.authentify.bz/api/v2/approval-requests/$APPROVAL_REQUEST_ID \
  -H "x-api-key: $AUTHENTIFY_ACCOUNT_KEY"

It returns the status (pending, approved or rejected) and the votes, with who cast them. GET /api/v2/approval-requests?status=pending lists the ones still waiting.

Once approved, run the action. If your API requires a decision token, the agent fetches one with POST /api/v2/authorization-requests/:id/decision-token.

Votes can't come from code

POST /api/v2/approval-requests/:id/approve and /reject accept only a signed-in person. The approver is taken from their session, never from the request body, and API keys are refused. The SDKs' approve and reject methods throw for this reason. This keeps an agent, or anyone holding a key, from approving its own requests.

When the person decides instead

If the agent acts for one person and you've turned on end_user_approval for it, that person can approve or deny the action themselves. See single-action approvals.