Activate Soft OTP

Activates SmartOTP on a device and returns the client secret key plus the TOTP configuration the SDK needs to generate codes.

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"
  }
}

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.
push_token	string	Yes	—	The client Firebase token, used to push the challenge key from server to client.
token	string	Yes	—	The registration token generated by Register.
activation_key	string	Yes	—	The activation key generated by Register. It behaves like an OTP code — call Register again for a fresh one before retrying.
registration_id	string	No	—	The registration ID from Register.
device_id	string	No	—	The device UUID.
device_os	string	No	—	The device operating system.
app_version	string	No	—	The client app version.
metadata	object	No	—	Additional key-value information to store with the activation.

Returns: ActivateResponse

INFO

The endpoint is /api/v1/saas-sotp/activate. Contact the CAKE team if you get a 404.

Sample 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"
  }
}

Field	Type	Description
success	bool	Request status.
code	int	The status code — 1 on success.
data.key	string	The client secret key used to generate OTPs.
data.period	int	The number of seconds an OTP stays valid.
data.algorithm	string	The HMAC algorithm — HmacSHA512.
data.length	int	The number of digits in an OTP code.
data.type	string	The type of soft OTP — totp.
data.issuer	string	The issuer that generated the OTP.

WARNING

key is the client secret. Hand it straight to the SDK, which stores it behind the user's PIN — never log it, never persist it server-side alongside the user record, and never return it to any caller other than the activating device. Anyone holding it can generate valid basic OTPs indefinitely.

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.
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. The activation_key did not match.
125	OTP hết hạn sử dụng — OTP expired. Call Register for a new activation key.
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.

Next Steps

• Validate OTP — verify the first code generated from this secret
• Sync Time — reconcile the device clock before generating codes