Xác minh xác thực hai lớp

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
}

Gọi endpoint này sau khi đăng nhập bằng mật khẩu hoặc tiếp tục phiên trả status: "mfa_required". Gửi cookie vos_mfa_challenge nhận được từ yêu cầu trước. Dùng cookie jar cho client dòng lệnh hoặc server. Client trình duyệt phải gửi yêu cầu cùng origin với máy chủ xác thực. Cookie là HttpOnly; coi giá trị cookie là thông tin xác thực và không tự sửa nội dung. Endpoint không yêu cầu Bearer JWT. Phản hồi yêu cầu xác thực không cung cấp token phiên hoặc mã định danh yêu cầu để gửi trong body.

`method`	`code`	Điều kiện
`totp`	Mã hiện tại trong ứng dụng xác thực, dưới dạng chuỗi gồm đúng 6 chữ số. Giữ nguyên số 0 ở đầu.	`totp` có trong `methods` của yêu cầu xác thực.
`lookup_secret`	Một mã dự phòng đã lưu và chưa sử dụng, dưới dạng chuỗi.	`lookup_secret` có trong `methods`. Xác minh thành công sẽ tiêu thụ mã này.

Chỉ gửi method và code. Các trường body bổ sung bị từ chối. Quy trình đăng nhập có ví dụ cURL đầy đủ với cách giữ cookie.

Xác minh thành công

HTTP 200 trả status: "authenticated", sessionToken, jwt, session, identity và tokenizedSession. Cả hai đối tượng phiên có authenticator_assurance_level: "aal2". Phản hồi xoá cookie xác thực đang chờ. Gửi jwt qua Authorization: Bearer <jwt> khi gọi REST API cần xác thực. Với khôi phục mật khẩu, giữ tất cả cookie đã cập nhật và tiếp tục yêu cầu đặt lại mật khẩu sau khi xác minh thành công.

Xử lý lỗi

Mã HTTP	Mã lỗi	Bước tiếp theo
`400`	`invalid_code`	Gửi đúng phương thức và định dạng mã.
`400`	`invalid_mfa_request`	Kiểm tra mã và thử lại khi yêu cầu xác thực còn hiệu lực. Không dùng lại mã dự phòng đã tiêu thụ.
`401`	`session_invalid`	Đăng nhập lại.
`403`	`origin_not_allowed`	Gửi yêu cầu cùng origin với máy chủ xác thực hoặc dùng server client.
`403`	`session_invalid`, `session_refresh_required`, `session_aal2_required`	Bắt đầu xác thực lại và hoàn tất các bước bắt buộc.
`410`	`challenge_expired`, `flow_expired`	Đăng nhập hoặc tiếp tục phiên lại để nhận yêu cầu xác thực và cookie mới.
`429`	`rate_limited`	Chờ trước khi thử lại.
`502`	`mfa_incomplete`, `mfa_service_unavailable`	Chưa có JWT được cấp. Thử lại sau.

Ủy quyền

vos_mfa_challenge

string

bắt buộc

Cookie xác thực hai lớp đang chờ, được trả về khi đăng nhập hoặc tiếp tục phiên. Dùng cookie jar; không tự tạo hoặc sửa giá trị cookie.

Nội dung

application/json

Phương thức và mã xác thực yếu tố thứ hai.

Option 1
Option 2

Một bằng chứng xác thực yếu tố thứ hai. Chọn phương thức có trong phản hồi yêu cầu xác thực.

method

enum<string>

bắt buộc

Chọn xác minh bằng mã trong ứng dụng xác thực. Phải có trong methods của yêu cầu xác thực.

Tùy chọn có sẵn:

totp

code

string

bắt buộc

Chuỗi gồm đúng 6 chữ số, giữ nguyên số 0 ở đầu.

Required string length: 6

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

Ví dụ:

"012345"

Phản hồi

Xác thực hai lớp hoàn tất; JWT đã được cấp.

Xác thực hoàn tất. JWT chỉ được cấp sau khi đáp ứng tất cả yếu tố xác thực bắt buộc.

status

enum<string>

bắt buộc

Cho biết xác thực đã hoàn tất và JWT có thể được sử dụng.

Tùy chọn có sẵn:

authenticated

sessionToken

string

bắt buộc

Token phiên tài khoản. Giữ bí mật token này. Dùng để tiếp tục phiên; dùng jwt để xác thực REST API.

jwt

string

bắt buộc

Bearer JWT cho yêu cầu REST API cần xác thực. Gửi bằng Authorization: Bearer .

session

object

bắt buộc

Phiên đã xác thực và đang hoạt động.

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

Thông tin danh tính tài khoản của phiên đã xác thực, hoặc null nếu phản hồi không có danh tính.

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>

Mức xác thực của phiên: aal1 sau khi xác thực yếu tố thứ nhất; aal2 sau khi xác thực hai lớp thành công.

Tùy chọn có sẵn:

aal1,

aal2

identity

object | null

bắt buộc

Danh tính tài khoản, hoặc null nếu không có.

Hide child attributes

identity.id

string

Unique identifier for the record.

identity.traits

object

Account attributes returned with the authenticated session.

tokenizedSession

object

bắt buộc

Phiên đã xác thực chứa JWT trong trường 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

Thông tin danh tính tài khoản của phiên đã xác thực, hoặc null nếu phản hồi không có danh tính.

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>

Mức xác thực của phiên: aal1 sau khi xác thực yếu tố thứ nhất; aal2 sau khi xác thực hai lớp thành công.

Tùy chọn có sẵn:

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
}

Tổng quan

Integrations

Authentication

REST API

Streaming API

FIX API

Xác minh xác thực hai lớp

Xác minh thành công

Xử lý lỗi

Ủy quyền

Nội dung

Phản hồi

​Cookie và phương thức bắt buộc

​Xác minh thành công

​Xử lý lỗi

Ủy quyền

Nội dung

Phản hồi

Cookie và phương thức bắt buộc

Xác minh thành công

Xử lý lỗi