Kích hoạt Soft OTP

Kích hoạt SmartOTP trên một thiết bị và trả về khóa bí mật của client (client secret key) cùng cấu hình TOTP mà SDK cần để tạo mã.

Endpoint

POST /api/v1/saas-sotp/activate
Content-Type: application/json

{
  "partner_id": "{{partner_id}}",
  "partner_key": "{{partner_key}}",
  "user_id": "{{user_id}}",
  "device_id": "{{device_id}}",
  "device_os": "{{device_os}}",
  "app_version": "{{app_version}}",
  "registration_id": "{{registration_id}}",
  "activation_key": "{{activation_key}}",
  "push_token": "{{push_token}}",
  "token": "{{token}}",
  "metadata": {
    "ios": "test",
    "version": "test"
  }
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
partner_id	string	Có	—	Partner ID.
partner_key	string	Có	—	Partner key.
user_id	string	Có	—	User ID.
push_token	string	Có	—	Firebase token của client, dùng để push khóa challenge từ server đến client.
token	string	Có	—	Token đăng ký được tạo bởi Đăng ký.
activation_key	string	Có	—	Activation key được tạo bởi Đăng ký. Nó hoạt động giống một mã OTP — hãy gọi lại Đăng ký để lấy một key mới trước khi thử lại.
registration_id	string	Không	—	Registration ID từ Đăng ký.
device_id	string	Không	—	UUID của thiết bị.
device_os	string	Không	—	Hệ điều hành của thiết bị.
app_version	string	Không	—	Phiên bản ứng dụng client.
metadata	object	Không	—	Thông tin key-value bổ sung để lưu cùng với lần kích hoạt.

Trả về: ActivateResponse

INFO

Endpoint là /api/v1/saas-sotp/activate. Hãy liên hệ đội CAKE nếu bạn gặp lỗi 404.

Ví dụ request

curl --location --request POST '<BASE_URL>/saas-sotp/activate' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "partner_id": "{{partner_id}}",
    "partner_key": "{{partner_key}}",
    "user_id": "{{user_id}}",
    "device_id": "{{device_id}}",
    "device_os": "{{device_os}}",
    "app_version": "{{app_version}}",
    "registration_id": "{{registration_id}}",
    "activation_key": "{{activation_key}}",
    "push_token": "{{push_token}}",
    "token": "{{token}}",
    "metadata": {
      "ios": "test",
      "version": "test"
    }
  }'

Response

{
  "success": true,
  "code": 1,
  "message": "success",
  "data": {
    "key": "fake_client_secret_key",
    "period": 15,
    "algorithm": "HmacSHA512",
    "length": 6,
    "type": "totp",
    "issuer": "SOTP"
  }
}

Trường	Kiểu	Mô tả
success	bool	Trạng thái của request.
code	int	status code — 1 khi thành công.
data.key	string	Khóa bí mật của client dùng để tạo OTP.
data.period	int	Số giây một OTP còn hiệu lực.
data.algorithm	string	Thuật toán HMAC — HmacSHA512.
data.length	int	Số chữ số của một mã OTP.
data.type	string	Loại soft OTP — totp.
data.issuer	string	Issuer đã tạo ra OTP.

WARNING

key là khóa bí mật của client. Hãy chuyển thẳng nó cho SDK, nơi lưu nó phía sau PIN của người dùng — không bao giờ ghi log, không bao giờ lưu ở phía server cùng bản ghi người dùng, và không bao giờ trả về cho bất kỳ bên gọi nào khác ngoài thiết bị đang kích hoạt. Bất kỳ ai nắm được nó đều có thể tạo OTP cơ bản hợp lệ vô thời hạn.

Lỗi

Mã	Mô tả
3	Parameter invalid
103	Thông tin Partner không chính xác — Partner details are incorrect.
121	Yêu cầu vượt giới hạn. Vui lòng thử lại sau ít phút. — Request limit exceeded.
123	Yêu cầu vượt giới hạn. Vui lòng thử lại sau ít phút. — Request limit exceeded.
124	OTP không hợp lệ — Invalid OTP. activation_key không khớp.
125	OTP hết hạn sử dụng — OTP expired. Hãy gọi Đăng ký để lấy một activation key mới.
126	Có lỗi xảy ra vui lòng thử lại — An error occurred, please retry.
129	Token không hợp lệ — Invalid token.

Bước tiếp theo

• Xác minh OTP — xác minh mã đầu tiên được tạo từ secret này
• Đồng bộ thời gian — đối chiếu đồng hồ thiết bị trước khi tạo mã