External API

The External API is a separate surface, under /v1, for machine-to-machine integrations. It authenticates with an API key instead of a user token, and it returns a slightly different error shape from the rest of the API. Use it when one of your own services needs to drive assisted login — typically to submit a one-time code or to check whether one is needed.

Before you can call it, create an API key with the scopes you need.

Base path

Every endpoint here lives under /v1, served from the same self-hosted base URL described in the overview, for example:

https://reconbanker.your-domain.com/v1

Authentication

The External API accepts an API key in either of two headers:

Authorization: Api-Key rbk_abcd1234_secret...

x-api-key: rbk_abcd1234_secret...

It never accepts a Bearer JWT — that token is only for the dashboard API. Likewise, an API key does not work on the JWT endpoints. See API keys for how keys, scopes, and account restrictions work.

Error shape

The External API returns errors as a structured object, which differs from the { "error": "message" } shape used everywhere else:

{ "error": { "code": "FORBIDDEN", "message": "Forbidden" } }

Submit an OTP code

Use this endpoint to deliver a one-time code to a login that is waiting for one. Requires the otp:write scope.

POST /v1/accounts/:accountId/otp
Content-Type: application/json
Authorization: Api-Key rbk_abcd1234_secret...

Request body:

{ "code": "123456" }

• code - required. 1 to 32 characters.

Response 202 Accepted:

{ "submitted": true }

The code is forwarded to the in-progress bank login. A 202 means Reconbanker accepted the code for delivery, not that the bank has confirmed it — watch the account status, the notification webhook, or the realtime stream for the outcome.

This endpoint is rate-limited. The same action is available to a human in the dashboard via POST /accounts/:accountId/otp (see Accounts).

Get account status

Use this endpoint to check whether an account has a session running and whether it is currently waiting for a one-time code. Requires the status:read scope.

GET /v1/accounts/:accountId/status
Authorization: Api-Key rbk_abcd1234_secret...

Response 200 OK:

{
  "account_id": "b9c224b3-3c2b-42bd-b23e-337ae0185690",
  "session_running": true,
  "pending_assistance": {
    "id": "req-1",
    "type": "otp",
    "descriptor": { "length": 6, "type": "numeric", "purpose": "login" },
    "attempts": 2
  }
}

When nothing is pending, pending_assistance is null:

{
  "account_id": "b9c224b3-3c2b-42bd-b23e-337ae0185690",
  "session_running": false,
  "pending_assistance": null
}

• session_running - true while a bank session is active for the account.
• pending_assistance - the request waiting for a code, or null.
• descriptor.length - how many characters the code has.
• descriptor.type - "numeric" or "alphanumeric".
• descriptor.purpose - optional hint about what the code is for, such as "login".
• attempts - how many codes have already been tried for this request.

Push or poll

Your service can find out a code is needed in two ways: receive a push through the notification webhook, or poll this status endpoint until pending_assistance is non-null. The Automate OTP submission guide walks through both.

See also

• API keys - create the credential these endpoints require.
• Automate OTP submission - end-to-end integration guide.
• Assisted login and OTP - the concept behind these endpoints.
• Notification settings - get pushed an event instead of polling.