TsByin 2FA

Tiếng Việt

English

Tiếng Việt

English

Appearance

Hướng dẫn Tích hợp B2B API ​

Để nhúng TsByin 2FA vào các ứng dụng bên ngoài của bạn (như trang web thương mại điện tử, bảng điều khiển nội bộ, v.v.), bạn có thể sử dụng API cấp phát Server-to-Server của chúng tôi.

1. Xác thực (Authentication) ​

Tất cả các API tích hợp đều yêu cầu xác thực thông qua API Key. Bạn có thể tạo một API Key từ tab Integrations (B2B) trong bảng điều khiển của ứng dụng TsByin 2FA.

Gửi API Key này trong phần Authorization của header HTTP dưới dạng Bearer token:

http
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Cấp phát Mã 2FA Mới (Provisioning) ​

Sử dụng endpoint này để tạo mới một mã bí mật (TOTP secret) cho một người dùng trong ứng dụng của bạn. Chúng tôi sẽ lưu trữ mã này dưới dạng không mã hóa (plaintext) trên Edge Database để có thể tự động kiểm tra mã thay cho bạn.

Endpoint: POST https://api-2fa.tsbyinchei.workers.dev/v1/secrets

Request Body:

json
{
  "project_id": "prj_abc123...",
  "user_identifier": "[email protected]",
  "issuer": "My E-commerce App"
}

Response:

json
{
  "success": true,
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_url": "otpauth://totp/My%20E-commerce%20App:user%40example.com?secret=JBSWY3DPEHPK3PXP&issuer=My%20E-commerce%20App&algorithm=SHA1&digits=6&period=30"
}

Lưu ý: Bạn nên sử dụng otpauth_url được trả về để tạo mã QR Code (bằng các thư viện như qrcode trên frontend của bạn), qua đó người dùng có thể quét nó vào ứng dụng Google Authenticator hoặc Authy của họ.

3. Xác thực Mã 2FA (Verifying) ​

Khi người dùng đăng nhập vào ứng dụng của bạn, họ sẽ cung cấp một mã gồm 6 chữ số. Hãy gửi mã này đến verification endpoint của chúng tôi để kiểm tra xem nó có hợp lệ hay không.

Endpoint: POST https://api-2fa.tsbyinchei.workers.dev/v1/verify

Request Body:

json
{
  "project_id": "prj_abc123...",
  "user_identifier": "[email protected]",
  "totp_code": "123456"
}

Response (Thành công):

json
{
  "success": true,
  "message": "Verified"
}

Response (Thất bại):

json
{
  "success": false,
  "error_code": "INVALID_CODE",
  "attempts_left": 3
}

Hướng dẫn Test thử bằng Postman ​

  1. Tạo một Project bên trong ứng dụng TsByin 2FA.
  2. Copy lại Project ID và API Key.
  3. Sử dụng Postman để gọi POST /v1/secrets với API Key của bạn để lấy một mã secret mới.
  4. Nhập mã secret đó vào ứng dụng Authenticator trên điện thoại của bạn (hoặc dùng các công cụ lập trình) để lấy mã 6 chữ số.
  5. Gọi POST /v1/verify bằng Postman với API Key và mã 6 số vừa tạo để kiểm tra kết quả.