The Recipient Auth Ladder

What “auth methods” actually means here

Think of auth_methods as a checklist of gates the recipient must clear before they are allowed to treat the session as a normal signing flow. Verdocs does not run them in “whatever order the JSON happened to serialize.” It applies a single, platform-defined sequence every time.

That order is fixed so behavior stays consistent for your app, for signers, and for support. Reordering the array in your request does not reorder the gates.

Rough ladder (first incomplete method wins)

If a method is not in auth_methods, it is skipped. If it is included, earlier methods must reach complete (or equivalent) before later ones are even considered.

---

Failure is a full stop (by design)

If any configured method’s state becomes failed, the recipient cannot continue. The API returns a clear error asking them to contact the sender, and a recipient_auth_fail webhook is available so your backend can react (pause CRM state, alert ops, and so on).

For some methods, repeated wrong answers eventually mark the method failed and may notify the sender—not on every single wrong keystroke. That pattern reduces noise and lowers the risk of a malicious signer spamming your sender’s inbox.

---

Where the ladder runs (why refresh behaves)

Whenever a signer starts or resumes a signing session, the API reloads envelope and recipient data and re-evaluates which gate applies from stored state—not from whatever your SPA last assumed.

That is why a browser refresh “snaps” the user back to the correct step: durable fields such as auth_step, auth_method_states, and KBA-related session data are the source of truth.

Your front end should render the next UI from the signing session response and the recipient object you get back from Verdocs, not only from the template defaults you used at send time.

---

Verify signer: one endpoint, several modes

Signers complete gates through the Verify signer API while using a signing session token—not your organization’s API key. The request names which auth_method this round is for (passcode, email, kba, and so on).

Patterns that trip people up the first time:

• Passcode / email OTP: Wrong answers increment toward a hard failure; after enough failures the method can move to failed, the sender may be notified, and webhooks may fire—read response messages carefully.
• **KBA: **Early calls often supply identity fields; later calls supply responses for challenge or follow-up phases. There is a bounded verification window tied to when the step started (auth_started). If the signer waits too long, the flow can time out, fail the method, and notify the sender.
• **Already complete: **Calling verify again for a method that is already complete should return a fresh signing payload instead of forcing the user through the gate again.

For product context on which methods exist and how they behave at a high level, see New Recipient Authentication Options in What’s New.

Starting or refreshing the session itself is covered under Start Signing Session.