Assisted login and OTP

When an account uses login_mode: assisted (see Sessions), Reconbanker does not log in unattended. Instead, if the bank prompts for a second factor, Reconbanker pauses the login and asks for the one-time code. This page explains what that request looks like and how the code gets back to it.

The assistance request

When the bank asks for a code, Reconbanker creates an assistance request against the account. It describes what the bank wants:

• descriptor.length - how many characters the code has.
• descriptor.type - "numeric" or "alphanumeric".
• descriptor.purpose - an optional hint such as "login".
• attempts - how many codes have already been tried.

There is at most one pending assistance request per account at a time.

Lifecycle

A request moves through these states:

• pending - waiting for a code.
• fulfilled - a code was submitted and accepted; the login continues.
• cancelled - the request was withdrawn (for example, the session was stopped).
• expired - no code arrived in time, so the login timed out and failed.

A failed assisted login counts toward the account's skip-on-fatal protection like any other login failure.

Two ways to supply the code

The same request can be fulfilled by either of two paths:

• A human, in the dashboard. An operator sees the OTP prompt and types the code. Under the hood the dashboard calls GET /accounts/:accountId/otp to recover the pending request and POST /accounts/:accountId/otp to submit the code (see Accounts).
• One of your services, through the External API. A machine integration submits the code with POST /v1/accounts/:accountId/otp using an API key that has the otp:write scope. This is how an SMS-relay server can complete logins with no human involved.

Both paths feed the same in-progress login, so you can use whichever fits an account — or fall back to a human when automation is unavailable.

How an external service learns a code is needed

A machine integration finds out a code is pending in one of two ways:

• Push - subscribe the account to the notification webhook for the assistance_required event. Reconbanker POSTs your endpoint the moment a code is requested.
• Poll - call GET /v1/accounts/:accountId/status and watch for pending_assistance to become non-null.

Either way, once it has the code (for example, from an incoming SMS), the service submits it with POST /v1/accounts/:accountId/otp.

Next

• Automate OTP submission - build the integration end to end.
• External API - the /v1 endpoints for status and submission.
• API keys - the credential a machine integration uses.
• Notification settings - get pushed the assistance_required event.
• Sessions - where login_mode: assisted is configured.