# The Recipient Auth Ladder (/docs/guides/tutorials/the-recipient-auth-ladder)


## What “auth methods” actually means here [#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) [#rough-ladder-first-incomplete-method-wins]

| Order | Method       | What “next” usually looks like                                                                                                                                                                   |
| ----- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1     | **Passcode** | Recipient must satisfy the passcode step (see `auth_step` and related state on the recipient) before anything below is considered.                                                               |
| 2     | **Email**    | OTP-style flow: a verification window, optional resend, then validating a short-lived code.                                                                                                      |
| 3     | **SMS**      | Same overall shape as email in the product model. Confirm in your environment and contract before you promise SMS in customer-facing copy - capabilities can differ by rollout or configuration. |
| 4     | **KBA**      | Identity verification: collect required identity fields, then challenge questions or follow-up steps from the provider, then complete or fail.                                                   |
| 5     | **ID**       | Additional identity verification where enabled. Treat as optional until your account team confirms it is supported for your use case.                                                            |

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) [#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) [#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 [#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*.