Giới thiệu
2-Factor Authentication (Xác thực 2 yếu tố): Là một giải pháp bảo mật sử dụng công nghệ Cloud messaging để xác nhận danh tính của người dùng và bảo vệ hệ thống khỏi các cuộc tấn công lừa đảo. Một mã PIN (sử dụng 1 lần) được tạo ra và gửi tới số điện thoại của người dùng (sms hoặc voice call). Người dùng nhận được mã PIN và nhập vào ứng dụng để xác nhận danh tính. Nếu mã PIN nhập vào là đúng người dùng mới được phép tiếp tục các bước tiếp theo để sử dụng ứng dụng.
SpeedSMS 2-Factor Authentication API (2FA API) cho phép bạn dễ dàng thêm một lớp bảo mật vào hệ thống của bạn thông qua một API duy nhất. Ngoài ra bạn cũng có thể sử dùng 2FA API để tạo và gửi mã xác nhận tới người dùng.
API URL
Tất cả các API sẽ được bắt đầu bằng địa chỉ url:
http://api.speedsms.vn/index.php/
Hoặc
https://api.speedsms.vn/index.php/
Các bạn nên sử dụng địa chỉ HTTPS để đảm bảo tính bảo mật.
Authentication
Để sử dụng 2FA API bạn cần phải đăng ký một tài khoản tại địa chỉ https://connect.speedsms.vn. Mỗi tài khoản đăng ký sẽ được cấp một API access token. Ứng dụng của bạn sẽ sử dụng API access token này để xác thực (authenticate) với SpeedSMS.
API access token được gửi kèm với bản tin HTTP request thông qua cơ chế xác thực HTTP Basic Authentication. Trong đó API access token sẽ đóng vai trò như là một username.
Ví dụ: để gọi API thông qua curl:
curl -i -u "{API access token}:x" "https://api.speedsms.vn/index.php/user/info"
Để lấy API access token, bạn vui lòng đăng nhập tại địa chỉ https://connect.speedsms.vn, sau đó click vào menu "Settings" -> "Profile" để lấy thông tin API access token
Rate limit
SpeedSMS 2FA API cho phép ưng dụng của bạn gọi tối đa 60 requests trong vòng 60 giây. Nếu bạn gọi quá số lần requests. Bạn sẽ nhận được response:
{"name":"Too Many Requests","message":"Rate limit exceeded.","code":0,"status":429}
Lúc này bạn cần phải kiểm tra tham số X-Rate-Limit-Reset trong header của bản tin HTTP để lấy số giây cần phải đợi và thực hiện cơ chế sleep trước khi tiếp tục thực hiện requests.Trong trường hợp bạn cần nhiều hơn 60 requests vui lòng liên hệ để chúng tôi nâng hạn mức cho bạn.
Error codes
- 007: IP locked
- 008: Account blocked
- 009: Account not allow to call the API
- 101: Invalid or missing parameters
- 105: Phone number invalid
- 300: Your account balance not enough to send sms
- 500: Internal error, please try again
API tạo mã PIN
POST /pin/create API cho phép bạn tạo ra một mã PIN và gửi mã PIN này tới người dùng theo cấu hình của 2FA application đã tạo trước đó.
Gọi API thông qua curl:
curl -i -u "{Access token}" -H "Content-Type: application/json" -X POST -d '{"to": "phone number", "content": "noi dung sms", "app_id": "2FA Application ID"}' https://api.speedsms.vn/index.php/pin/create
- to: số điện thoại của người nhận mã PIN (lưu ý: số điện thoại ở dạng: 09x, 01x)
- content: Nội dung của tin nhắn, đây là tham số tùy chọn không bắt buộc nếu phương thức gửi mã PIN là sử dụng voice call. Trong trường hợp phương thức gửi mã PIN sử dụng SMS thì nội dung tin nhắn cần phải chứa từ khóa {pin_code}, từ khóa này sẽ được thay thế bằng mã PIN mà SpeedSMS tạo ra.
- app_id: Là mã ID của ứng dụng mà bạn đã tạo.
ví dụ: {"to": "0912345678", "content": "Your verification code is: {pin_code}", "app_id": "1234567890"}
Success response:
{ "status": "success", "code": "00", "data": { "pin_code": "generated pin code", "tranId": "transaction id", "totalPrice": total price number } }
- pin_code: mã PIN đã được SpeedSMS tạo thành công và gửi tới người dùng
- tranId: được sử dụng để tra cứu trạng thái của sms/voice call vừa gửi
- totalPrice: Tổng chi phí, chi phí sẽ dựa vào phương thức mà bạn sử dụng để gửi mã PIN
Error response:
{ "status": "error", "code": "error code", "message": "error description" }
API verify mã PIN
POST /pin/verify API cho phép bạn verify nếu mã PIN người dùng nhập vào là đúng hoặc sai
Gọi API thông qua curl:
curl -i -u "{Access token}" -H "Content-Type: application/json" -X POST -d '{"phone": "phone number", "app_id": "Application id", "pin_code": "mã PIN mà người dùng nhập vào"}' https://api.speedsms.vn/index.php/pin/verify
- phone: số điện thoại của người nhận mã PIN (lưu ý: số điện thoại ở dạng: 09x, 01x)
- pin_code: mã PIN mà người dùng đã nhập
- app_id: Là mã ID của ứng dụng mà bạn đã tạo.
ví dụ: {"phone": "0912345678", "pin_code": "1234", "app_id": "1234567890"}
Success response:
{ "status": "success", "data": { "pin": "Mã pin mà người dùng đã nhập", "phone": "số điện thoại của người dùng", "verified": true/fale, "remainingAttempts": số lần được phép nhập lại mã pin nếu nhập sai trước đó } }
pin: Mã pin mà người dùng đã nhập vào ứng dụng
phone: Số điện thoại nhận mã PIN
verified: true/false (cho biết mã PIN đã nhập vào là đúng hay sai, true: đúng, false: sai)
remainingAttempts: Số lần người dùng được phép nhập lại mã pin nếu đã nhập sai ở lần nhập trước
Error response:
{ "status": "error", "code": "error code", "message": "error description" }