​

Second-officer approvals for Verify

​

1. What an approval gates

• OTP template changes (otp_template) — new submissions and edits to the per-channel message bodies on your verification profiles (the copy a recipient reads in an SMS, WhatsApp, email, or voice OTP).
• Resend-burst windows (resend_burst) — a burst of POST /verify/resend calls against one verification. Tight resend limits starve a flaky integration; overly wide limits invite OTP-burst abuse, so widening the burst count gets a second set of eyes.

​

2. Roles: requester and approver

• Requester — any team member who edits OTP templates or triggers resends (typically a member or developer role). When the gate is on and their change is gated, the request lands in the approvals queue instead of applying.
• Approver — an owner or admin. They read the queue, judge each item, and approve or reject it. Only owners and admins can see the queue or edit the policy; other roles get a access-restricted notice and the API answers 403.

​

3. Workflow: request → approve or reject → execute

1. Requester queues the change. They edit a template on the Verify → Configuration surface, or drive enough resends against one verification to exceed the configured burst threshold. Instead of applying, the change enters the pending queue and the caller receives a gated: true response telling them which kind queued.
2. Approver opens the queue. In the dashboard they navigate to Outbound → OTP approvals. The queue lists pending items oldest-first, each showing the kind, the requester’s name, and the exact rendered template body (or the burst count and window) they are judging.
3. Decision. The approver clicks Approve or Reject. Reject may carry an optional reason (up to 1,000 characters) that goes back to the requester.
4. Execution only on approval. An approved template’s rendered body is applied to its verification profile; an approved resend burst re-enters the normal Verify dispatch path (respecting cooldowns, rate limits, and channel fallback). A rejected item goes nowhere — and the requester can re-submit it, which queues a fresh row.

​

4. Audit trail

• verify.approval.approved — a second officer released an item.
• verify.approval.rejected — with the reason in the detail payload.
• verify.approval.settings.updated — a policy edit, with the new values.

​

5. Turn the gate on (worked examples)

​

5.1 Gate OTP template changes

curl -X PUT "https://api.orbit.devotel.io/api/v1/verify/approvals/settings" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "require_approval_default": true }'

{
  "data": {
    "require_approval_default": true,
    "resend_burst_threshold": null,
    "resend_burst_window_seconds": 60
  },
  "meta": {
    "request_id": "req_approvals_settings_01",
    "timestamp": "2026-09-04T09:00:00.000Z"
  }
}

​

5.2 Widen the resend-burst window

curl -X PUT "https://api.orbit.devotel.io/api/v1/verify/approvals/settings" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "require_approval_default": true,
    "resend_burst_threshold": 25,
    "resend_burst_window_seconds": 300
  }'

Prerequisites and expected result: you need an owner or admin role and a verify:write-capable key. On success the policy applies immediately — changes that match the gate start queueing from the next request onward.

​

6. Edge cases

• Time-expired requests. A queued resend burst can outlive its verification: if the verification expires while it waits, the approved replay is declined by the normal resend rules and the requester must start a fresh verification. The queue row stays pending so a supervisor can retry or reject it.
• Rejection comments. The optional reason is returned to the requester; keep it actionable (“Tighten the wording and re-submit”). A rejection never blocks re-submission — it queues a fresh row.
• Pending status on the configuration page. When a template edit queues, the requester sees it held as a pending approval instead of applied; the Verify → Configuration surface keeps showing the currently live body until a second officer releases the change. The pending queue itself lives only on Outbound → OTP approvals (owners and admins).
• Gate flips mid-flight. Turning the policy off stops new queueing; items already pending still need a decision before they execute.

​

See also

• OTP approvals reference — the policy fields, queue item shape, role rules, and the troubleshooting table.
• Audit log — the decision trail this gate writes to.
• Verify profiles: fallback chains and advanced factors — the profiles whose templates this gate protects.
• MFA factor suite — possession-of-secret factors alongside OTP delivery.