Register Soft OTP

Creates a device's SmartOTP registration and returns the registration_id, a one-time activation_key, and the device token. All three are required by Activate.

Endpoint

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

{
  "partner_id": "{{partner_id}}",
  "partner_key": "{{partner_key}}",
  "user_id": "{{user_id}}",
  "device_id": "{{device_id}}",
  "registration_time": "{{registration_time}}"
}

Parameters:

Param	Type	Required	Default	Description
partner_id	string	Yes	—	The partner id.
partner_key	string	Yes	—	The partner key.
user_id	string	Yes	—	The user id.
device_id	string	No	—	The device UUID.
registration_time	string	No	—	The time when this request was submitted.

Returns: RegisterResponse

INFO

user_id is required — the client secret is derived from it.

Sample Request

curl --location --request POST '<BASE_URL>/saas-sotp/register' \
  --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}}",
    "registration_time": "{{registration_time}}"
  }'

Response

{
  "success": true,
  "code": 1,
  "message": "success",
  "data": {
    "registration_id": "reg_00000001",
    "activation_key": "fake_activation_key",
    "token": "fake_device_token"
  }
}

Field	Type	Description
success	bool	Request status.
code	int	The status code — 1 on success.
data.registration_id	string	The unique registration ID.
data.activation_key	string	A one-time password used to activate SmartOTP on the device.
data.token	string	The user's access token, required by almost every other endpoint.

WARNING

The activation_key is single-use and short-lived. If activation fails, call Register again for a fresh key rather than retrying Activate with the old one.

Errors

Code	Description
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.
126	Có lỗi xảy ra vui lòng thử lại. — An error occurred, please retry.
190001	Thông tin không hợp lệ, device_id đã kích hoạt Soft-OTP — Device already has SmartOTP activated.

Codes 121 and 126 can also be returned. Handle them.

Next Steps

• Activate — exchange the activation key for the client secret
• Get Status — check whether a device is already registered