> ## Documentation Index > Fetch the complete documentation index at: https://docs.vos.verolabs.co/llms.txt > Use this file to discover all available pages before exploring further. # Xác minh xác thực hai lớp > Hoàn tất đăng nhập bằng mã trong ứng dụng xác thực hoặc mã dự phòng chưa sử dụng để lấy JWT Gọi endpoint này sau khi [đăng nhập bằng mật khẩu](/vi/apis/rest/auth/post-api-auth-login) hoặc [tiếp tục phiên](/vi/apis/rest/auth/post-api-auth-mfa-resume) trả `status: "mfa_required"`. ## Cookie và phương thức bắt buộc 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](/vi/apis/rest/auth/post-api-auth-login) 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 ` khi gọi REST API cần xác thực. Với [khôi phục mật khẩu](/vi/apis/rest/auth/post-api-auth-recovery-verify), 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. | ## OpenAPI ````yaml openapi.oms.vi.json POST /api/auth/mfa/verify openapi: 3.0.3 info: title: VOS OMS Public API version: 1.0.0 description: >- Public REST API surface for Vero OMS. Authentication requests use platform.verolabs.co. REST API requests use api-oms.verolabs.co. servers: - url: https://platform.verolabs.co description: Authentication host - url: https://api-oms.verolabs.co description: REST API host security: [] tags: - name: Authentication description: >- Đăng nhập bằng mật khẩu, xác thực hai lớp, tiếp tục phiên và khôi phục mật khẩu. - name: Trading description: Order entry, quote, IOI, and trading activity APIs. - name: Portfolio & Risk description: Accounts, holdings, mappings, and risk-rule read APIs. - name: Administration description: Permissions, groups, workflow, reference data, and audit APIs. - name: System & Diagnostics description: Health and latency endpoints. paths: /api/auth/mfa/verify: post: tags: - Authentication summary: Xác minh xác thực hai lớp description: >- Hoàn tất yêu cầu xác thực đang chờ bằng mã 6 chữ số trong ứng dụng xác thực hoặc mã dự phòng chưa sử dụng. Gửi cookie từ bước đăng nhập hoặc tiếp tục phiên. Không yêu cầu Bearer JWT. Khi thành công, trả status=authenticated, phiên aal2 và JWT, sau đó xoá cookie xác thực. Yêu cầu từ trình duyệt phải cùng origin với máy chủ xác thực. operationId: post_api_auth_mfa_verify requestBody: required: true description: Phương thức và mã xác thực yếu tố thứ hai. content: application/json: schema: $ref: '#/components/schemas/AuthMfaVerifyRequest' examples: totp: summary: Mã trong ứng dụng xác thực value: method: totp code: '012345' backup_code: summary: Mã dự phòng đã lưu và chưa sử dụng value: method: lookup_secret code: responses: '200': description: Xác thực hai lớp hoàn tất; JWT đã được cấp. content: application/json: schema: $ref: '#/components/schemas/AuthAuthenticatedResponse' examples: authenticated: summary: Xác thực hoàn tất value: status: authenticated sessionToken: jwt: session: active: true authenticator_assurance_level: aal2 tokenized: identity: null tokenizedSession: active: true authenticator_assurance_level: aal2 tokenized: headers: Set-Cookie: description: >- Xoá cookie vos_mfa_challenge đang chờ. Khi khôi phục mật khẩu, đồng thời cập nhật cookie khôi phục cho bước đặt lại mật khẩu. schema: type: string '400': description: >- Định dạng mã không hợp lệ (invalid_code), hoặc mã/yêu cầu bị từ chối (invalid_mfa_request). content: application/json: schema: $ref: '#/components/schemas/AuthError' '401': description: Phiên không còn hợp lệ (session_invalid). Đăng nhập lại. content: application/json: schema: $ref: '#/components/schemas/AuthError' '403': description: >- Origin hoặc điều kiện xác thực của phiên không được chấp nhận (origin_not_allowed, session_invalid, session_refresh_required, session_aal2_required). content: application/json: schema: $ref: '#/components/schemas/AuthError' '410': description: >- Cookie xác thực bị thiếu/hết hạn (challenge_expired), hoặc yêu cầu xác thực không còn hợp lệ (flow_expired). Đăng nhập hoặc tiếp tục phiên lại. content: application/json: schema: $ref: '#/components/schemas/AuthError' '429': description: Quá nhiều yêu cầu xác thực (rate_limited). content: application/json: schema: $ref: '#/components/schemas/AuthError' '502': description: >- Không thể hoàn tất xác thực hai lớp (mfa_incomplete, mfa_service_unavailable). content: application/json: schema: $ref: '#/components/schemas/AuthError' security: - mfaChallengeCookie: [] servers: - url: https://platform.verolabs.co components: schemas: AuthMfaVerifyRequest: description: >- 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. oneOf: - $ref: '#/components/schemas/AuthTotpVerifyRequest' - $ref: '#/components/schemas/AuthBackupCodeVerifyRequest' discriminator: propertyName: method mapping: totp: '#/components/schemas/AuthTotpVerifyRequest' lookup_secret: '#/components/schemas/AuthBackupCodeVerifyRequest' AuthAuthenticatedResponse: type: object description: >- 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. properties: status: type: string enum: - authenticated description: Cho biết xác thực đã hoàn tất và JWT có thể được sử dụng. sessionToken: type: string description: >- 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: type: string description: >- Bearer JWT cho yêu cầu REST API cần xác thực. Gửi bằng Authorization: Bearer . session: description: Phiên đã xác thực và đang hoạt động. allOf: - $ref: '#/components/schemas/AuthSession' identity: description: Danh tính tài khoản, hoặc null nếu không có. allOf: - $ref: '#/components/schemas/AuthIdentity' tokenizedSession: description: Phiên đã xác thực chứa JWT trong trường tokenized. allOf: - $ref: '#/components/schemas/AuthSession' required: - status - sessionToken - jwt - session - identity - tokenizedSession additionalProperties: false AuthError: type: object properties: error: type: string description: Machine-readable error code or error category. message: type: string description: Human-readable error message. status: type: integer format: int32 description: Mã trạng thái HTTP của phản hồi lỗi này. required: - error - message - status description: >- Cấu trúc lỗi xác thực. Dùng mã HTTP và trường error để quyết định bước tiếp theo. AuthTotpVerifyRequest: type: object description: Xác minh mã 6 chữ số hiện tại trong ứng dụng xác thực. properties: method: type: string enum: - totp description: >- 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. code: type: string minLength: 6 maxLength: 6 pattern: ^[0-9]{6}$ example: '012345' description: Chuỗi gồm đúng 6 chữ số, giữ nguyên số 0 ở đầu. required: - method - code additionalProperties: false AuthBackupCodeVerifyRequest: type: object description: Xác minh một mã dự phòng đã lưu và chưa sử dụng. properties: method: type: string enum: - lookup_secret description: >- Chọn xác minh bằng mã dự phòng. Phải có trong methods của yêu cầu xác thực. code: type: string minLength: 1 description: >- Mã dự phòng đã lưu và chưa sử dụng. Gửi nguyên mã dưới dạng chuỗi. Mã sẽ bị tiêu thụ sau khi xác minh thành công. required: - method - code additionalProperties: false AuthSession: type: object properties: id: type: string description: Unique identifier for the record. active: type: boolean description: Indicates whether the session is active. authenticated_at: type: string format: date-time description: Timestamp when the session was authenticated. expires_at: type: string format: date-time description: Timestamp when the session expires. devices: type: array items: $ref: '#/components/schemas/AuthSessionDevice' description: Devices associated with the authenticated session. identity: $ref: '#/components/schemas/AuthIdentity' tokenized: type: string description: Bearer JWT issued for REST API calls. authenticator_assurance_level: type: string enum: - aal1 - aal2 description: >- 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. description: >- Thông tin phiên đã xác thực. tokenized chứa Bearer JWT khi trường này có trong phản hồi. additionalProperties: true AuthIdentity: type: object properties: id: type: string description: Unique identifier for the record. traits: type: object additionalProperties: true description: Account attributes returned with the authenticated session. description: >- 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. additionalProperties: true nullable: true AuthSessionDevice: type: object properties: ip_address: type: string description: IP address reported for the session device. location: type: string description: Location metadata reported for the session device. user_agent: type: string description: User agent reported for the session device. description: AuthSessionDevice schema. securitySchemes: mfaChallengeCookie: type: apiKey in: cookie name: vos_mfa_challenge description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.