Mã TOTP / 2FA API

Thêm xác thực hai lớp: tạo secret TOTP kèm mã QR otpauth:// cho Google Authenticator, tính và kiểm tra mã 6–8 số (RFC 6238 / HOTP).

GETPOSThttps://apibox.io.vn/v1/totp

Bảo mật & Mã hoá▶ Dùng thử online

API TOTP giúp ứng dụng của bạn có xác thực hai lớp mà không cần thư viện. action=generate tạo secret Base32 ngẫu nhiên và URI otpauth:// với issuer của bạn và account của người dùng; action=qr trả về cùng nội dung dưới dạng mã QR PNG hoặc SVG để quét bằng Google Authenticator, Microsoft Authenticator, Authy hay 1Password. action=verify với secret và code kiểm tra mã người dùng nhập, mặc định chấp nhận lệch đồng hồ một chu kỳ (window).

action=code trả về mã hiện tại, mã kế tiếp và số giây mã hiện tại còn hiệu lực. Hỗ trợ SHA-1 (mặc định, mọi app đều dùng được), SHA-256 và SHA-512, 6 hoặc 8 chữ số, chu kỳ khác 30 giây và HOTP theo bộ đếm (RFC 4226) với type=hotp; mã sinh ra khớp với các vector kiểm thử của RFC.

Không có gì được lưu: secret đi kèm từng request và phản hồi không được cache. Hãy lưu secret đã mã hoá trong cơ sở dữ liệu của bạn, chống dùng lại mã bằng cách nhớ time_step được chấp nhận gần nhất của mỗi người dùng và giới hạn số lần thử.

Tham số

Tên	Vị trí	Kiểu	Bắt buộc	Mặc định
`action`	body\|query	string	không	`generate`	`generate`, `qr`, `code` hoặc `verify` (tự đoán theo tham số khác).
`secret`	body\|query	string	không		Secret Base32 (cho code / verify; tuỳ chọn khi generate).
`code`	body\|query	string	không		Mã cần kiểm tra.
`issuer`	body\|query	string	không		Tên ứng dụng hiển thị trong app xác thực.
`account`	body\|query	string	không		Nhãn người dùng, ví dụ email.
`digits`	body\|query	number	không	`6`	6–8 chữ số.
`period`	body\|query	number	không	`30`	Chu kỳ (giây).
`algorithm`	body\|query	string	không	`SHA1`	`SHA1`, `SHA256` hoặc `SHA512`.
`window`	body\|query	number	không	`1`	Số chu kỳ lệch được chấp nhận (verify).
`type`	body\|query	string	không	`totp`	`totp` hoặc `hotp` (dùng `counter`).

Ví dụ

curl "https://apibox.io.vn/v1/totp?issuer=APIBox&account=an@example.com" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/totp?issuer=APIBox&account=an@example.com', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/totp?issuer=APIBox&account=an@example.com",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/totp?issuer=APIBox&account=an@example.com');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Kết quả trả về

{
  "type": "totp",
  "secret": "OW7IHR3GMA57QTCFYF2WJ42XSPPCCUM7",
  "otpauth_uri": "otpauth://totp/APIBox%3Aan%40example.com?secret=OW7IHR3GMA57QTCFYF2WJ42XSPPCCUM7&issuer=APIBox&algorithm=SHA1&digits=6&period=30",
  "algorithm": "SHA1",
  "digits": 6,
  "period": 30,
  "current_code": "978344",
  "note": "Store the secret encrypted on your server; show the QR code (action=qr) once to the user."
}

Ứng dụng

Thêm 2FA cho trang đăng nhập SaaS trong một buổi chiều
Trang quản trị, công cụ nội bộ cần lớp xác thực thứ hai
Kiểm thử luồng authenticator khi QA
Sinh mã cho tài khoản dịch vụ trong script

Hỏi đáp

Có tương thích Google Authenticator không?

Có, với cấu hình mặc định (SHA-1, 6 số, 30 giây). Một số app bỏ qua thuật toán hoặc chu kỳ khác.

Secret có bị lưu lại không?

Không. Secret chỉ dùng để tính kết quả và phản hồi có Cache-Control: no-store. Bạn tự lưu secret, đã mã hoá.

Làm sao chặn dùng lại một mã?

verify trả về time_step; lưu giá trị được chấp nhận gần nhất của mỗi người dùng và từ chối mã có time_step bằng hoặc cũ hơn.

Mã TOTP / 2FA API

Tham số

Ví dụ

Kết quả trả về

Ứng dụng

Hỏi đáp

API liên quan

Tạo mã hash

Mã hoá / Giải mã

Tạo mật khẩu