OMKEY TOOLS

API mã xác thực hai yếu tố (2FA).

API này giúp ứng dụng tạo hoặc kiểm tra mã đăng nhập ngắn hạn, như một lớp bảo vệ bổ sung ngoài mật khẩu. Không cần tạo tài khoản lập trình viên hoặc API key.

Giải thích nhanh các thuật ngữ

Xác thực hai yếu tố (2FA): Đăng nhập cần hai cách xác minh khác nhau, ví dụ mật khẩu và một mã tạm thời.
Mã dùng một lần (OTP): Mã ngắn dùng để xác nhận đăng nhập hoặc một thao tác.
TOTP — mã đổi theo thời gian: Mã tự thay đổi theo đồng hồ, thường sau mỗi 30 giây. Các ứng dụng Authenticator thường dùng cách này.
HOTP — mã đổi theo lượt: Mã thay đổi khi yêu cầu mã tiếp theo, dựa trên số lượt thay vì thời gian.
Ứng dụng Authenticator: Ứng dụng trên điện thoại hoặc máy tính tạo mã đăng nhập tạm thời.
Khóa bí mật (secret): Thông tin riêng được ghép nối giữa tài khoản và ứng dụng tạo mã. Ai có khóa này có thể tạo mã tương ứng; không chia sẻ công khai.
API: Cách một ứng dụng yêu cầu ứng dụng khác thực hiện một việc.
OpenAPI: Tài liệu theo định dạng chung, mô tả địa chỉ API, dữ liệu gửi vào và kết quả trả về.

Các endpoint

POST /api/v1/2fa/secret/generate
POST /api/v1/2fa/totp/generate
POST /api/v1/2fa/totp/verify
POST /api/v1/2fa/hotp/generate
POST /api/v1/2fa/hotp/verify
POST /api/v1/2fa/uri/build
POST /api/v1/2fa/uri/parse
POST /api/v1/2fa/qr

Ứng dụng gửi dữ liệu dạng JSON qua HTTPS; không gửi mật khẩu tài khoản. Mỗi yêu cầu tối đa 4 KB; giới hạn 30 lần/phút cho mỗi địa chỉ mạng và 300 lần/phút toàn hệ thống. Hãy gọi từ phần xử lý phía sau của ứng dụng, không gọi trực tiếp từ trình duyệt của website khác. Lỗi trả về bằng JSON với mã và thông báo dễ đọc. Tài liệu OpenAPI 3.1.

Ví dụ tích hợp PHP

$response = file_get_contents('https://omkey.top/api/v1/2fa/totp/verify', false, stream_context_create(['http' => ['method' => 'POST', 'header' => "Content-Type: application/json\r\n", 'content' => json_encode(['secret' => $secret, 'code' => $code]), 'ignore_errors' => true]]));
$result = json_decode($response, true);
if ($result['data']['matches']) {
    // Kiểm tra nguyên tử matchedStep để từ chối mã đã dùng.
}

Bảo mật và quyền riêng tư

Khóa bí mật và mã xác thực được gửi đến Omkey qua HTTPS để tính toán. Yêu cầu không được lưu thành lịch sử xác minh; chỉ dùng dịch vụ này nếu cách xử lý dữ liệu phù hợp với bạn. API không lưu trạng thái xác minh: ứng dụng của bạn phải chống phát lại TOTP hoặc tăng HOTP counter nguyên tử sau khi hợp lệ. API không xác thực người dùng, tạo tài khoản hay quyết định đăng nhập. Với xác thực production, ưu tiên tính OTP trực tiếp trong hệ thống của bạn.

Endpoint qr trả URI otpauth làm payload, chưa phải ảnh QR. Hãy tạo ảnh QR trong ứng dụng của bạn.