Verify two-factor authentication

POST

https://platform.verolabs.co

api

auth

mfa

verify

curl --request POST \
  --url https://platform.verolabs.co/api/auth/mfa/verify \
  --header 'Content-Type: application/json' \
  --cookie vos_mfa_challenge= \
  --data '
{
  "method": "totp",
  "code": "012345"
}
'

{
  "status": "authenticated",
  "sessionToken": "<session-token>",
  "jwt": "<jwt>",
  "session": {
    "active": true,
    "authenticator_assurance_level": "aal2",
    "tokenized": "<jwt>"
  },
  "identity": null,
  "tokenizedSession": {
    "active": true,
    "authenticator_assurance_level": "aal2",
    "tokenized": "<jwt>"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

Call this endpoint after password login or session resumption returns status: "mfa_required". Send the vos_mfa_challenge cookie returned by the preceding request. Preserve it with a cookie jar for command-line or server clients. Browser clients must send requests from the authentication host origin. The cookie is HttpOnly and must be treated as an opaque credential. This endpoint does not require a Bearer JWT. The challenge response does not expose a session token or a challenge identifier to submit in the body.

`method`	`code`	Condition
`totp`	Current authenticator code as a string containing exactly six digits. Preserve leading zeros.	`totp` is listed in the challenge `methods`.
`lookup_secret`	One unused saved backup code as a string.	`lookup_secret` is listed in the challenge `methods`. Successful verification consumes the code.

Send only method and code. Additional body fields are rejected. See the login procedure for a complete cURL example with cookie handling.

Successful verification

HTTP 200 returns status: "authenticated", sessionToken, jwt, session, identity, and tokenizedSession. Both session objects report authenticator_assurance_level: "aal2". The response clears the pending challenge cookie. Send jwt as Authorization: Bearer <jwt> to protected REST API endpoints. For password recovery, preserve all updated cookies and continue to the password-reset request after successful verification.

Error handling

HTTP status	Error code	Next action
`400`	`invalid_code`	Send a valid method and code format.
`400`	`invalid_mfa_request`	Check the code and retry while the challenge remains valid. A consumed backup code cannot be reused.
`401`	`session_invalid`	Sign in again.
`403`	`origin_not_allowed`	Send the request from the authentication host origin or use a server client.
`403`	`session_invalid`, `session_refresh_required`, `session_aal2_required`	Restart authentication and complete its required steps.
`410`	`challenge_expired`, `flow_expired`	Restart login or session resumption to obtain a new challenge and cookie.
`429`	`rate_limited`	Wait before retrying.
`502`	`mfa_incomplete`, `mfa_service_unavailable`	No JWT was issued. Retry later.

Authorizations

vos_mfa_challenge

string

required

Pending two-factor challenge cookie returned by login or session resumption. Use a cookie jar; do not construct or modify its value.

Body

application/json

Second-factor method and code.

Option 1
Option 2

One second-factor proof. Choose a method listed in the challenge response.

method

enum<string>

required

Select authenticator-code verification. Must be available in the challenge methods.

Available options:

totp

code

string

required

Exactly six digits as a string, including any leading zeros.

Required string length: 6

Pattern: ^[0-9]{6}$

Example:

"012345"

Response

Two-factor authentication complete; JWT issued.

Completed authentication. The JWT is issued only after all required authentication factors pass.

status

enum<string>

required

Indicates that authentication is complete and the JWT can be used.

Available options:

authenticated

sessionToken

string

required

Account session token. Keep it confidential. Use it for session resumption; use jwt for REST API authorization.

jwt

string

required

Bearer JWT for protected REST API requests. Send it as Authorization: Bearer .

session

object

required

Active authenticated session.

Hide child attributes

session.id

string

Unique identifier for the record.

session.active

boolean

Indicates whether the session is active.

session.authenticated_at

string<date-time>

Timestamp when the session was authenticated.

session.expires_at

string<date-time>

Timestamp when the session expires.

session.devices

object[]

Devices associated with the authenticated session.

Hide child attributes

session.devices.ip_address

string

IP address reported for the session device.

session.devices.location

string

Location metadata reported for the session device.

session.devices.user_agent

string

User agent reported for the session device.

session.identity

object | null

Account identity returned with the authenticated session, or null if no identity is returned.

Hide child attributes

session.identity.id

string

Unique identifier for the record.

session.identity.traits

object

Account attributes returned with the authenticated session.

session.tokenized

string

Bearer JWT issued for REST API calls.

session.authenticator_assurance_level

enum<string>

Authentication assurance level: aal1 after first-factor authentication; aal2 after successful two-factor authentication.

Available options:

aal1,

aal2

identity

object | null

required

Account identity, or null if absent.

Hide child attributes

identity.id

string

Unique identifier for the record.

identity.traits

object

Account attributes returned with the authenticated session.

tokenizedSession

object

required

Authenticated session containing the JWT in tokenized.

Hide child attributes

tokenizedSession.id

string

Unique identifier for the record.

tokenizedSession.active

boolean

Indicates whether the session is active.

tokenizedSession.authenticated_at

string<date-time>

Timestamp when the session was authenticated.

tokenizedSession.expires_at

string<date-time>

Timestamp when the session expires.

tokenizedSession.devices

object[]

Devices associated with the authenticated session.

Hide child attributes

tokenizedSession.devices.ip_address

string

IP address reported for the session device.

tokenizedSession.devices.location

string

Location metadata reported for the session device.

tokenizedSession.devices.user_agent

string

User agent reported for the session device.

tokenizedSession.identity

object | null

Account identity returned with the authenticated session, or null if no identity is returned.

Hide child attributes

tokenizedSession.identity.id

string

Unique identifier for the record.

tokenizedSession.identity.traits

object

Account attributes returned with the authenticated session.

tokenizedSession.tokenized

string

Bearer JWT issued for REST API calls.

tokenizedSession.authenticator_assurance_level

enum<string>

Authentication assurance level: aal1 after first-factor authentication; aal2 after successful two-factor authentication.

Available options:

aal1,

aal2

curl --request POST \
  --url https://platform.verolabs.co/api/auth/mfa/verify \
  --header 'Content-Type: application/json' \
  --cookie vos_mfa_challenge= \
  --data '
{
  "method": "totp",
  "code": "012345"
}
'

{
  "status": "authenticated",
  "sessionToken": "<session-token>",
  "jwt": "<jwt>",
  "session": {
    "active": true,
    "authenticator_assurance_level": "aal2",
    "tokenized": "<jwt>"
  },
  "identity": null,
  "tokenizedSession": {
    "active": true,
    "authenticator_assurance_level": "aal2",
    "tokenized": "<jwt>"
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

{
  "error": "<string>",
  "message": "<string>",
  "status": 123
}

Overview

Integrations

Authentication

REST API

Streaming API

FIX API

Verify two-factor authentication

Successful verification

Error handling

Authorizations

Body

Response

​Required cookie and method

​Successful verification

​Error handling

Authorizations

Body

Response

Required cookie and method

Successful verification

Error handling