Sync Time

Returns the server's current timestamp and the TOTP configuration, so the device can detect clock drift. Because a code is only valid for 15 seconds, a device clock a minute out will fail every validation.

Endpoint

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

{
  "partner_id": "{{partner_id}}",
  "partner_key": "{{partner_key}}",
  "token": "{{token}}",
  "app_id": "{{app_id}}",
  "client_timestamp": "1672204839",
  "period": 15,
  "otp": "123456",
  "previous_otp": "654321"
}

Parameters:

Param	Type	Required	Default	Description
partner_id	string	Yes	—	The partner id.
partner_key	string	Yes	—	The partner key.
token	string	Yes	—	The registration token generated by Register.
period	int	Yes	—	The number of seconds an OTP stays valid.
app_id	string	No	—	The app id, used for tracking.
client_timestamp	int	No	—	The client's current timestamp.
otp	string	No	—	The current smart OTP.
previous_otp	string	No	—	The OTP from the previous time block.

Supplying otp and previous_otp lets the server work out how far the device clock has drifted, by finding which time block the codes actually belong to.

Returns: SyncTimeResponse

Sample Request

curl --location --request POST '<BASE_URL>/saas-sotp/sync-time' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data-raw '{
    "partner_id": "{{partner_id}}",
    "partner_key": "{{partner_key}}",
    "token": "{{token}}",
    "app_id": "{{app_id}}",
    "client_timestamp": "1672204839",
    "period": 15,
    "otp": "123456",
    "previous_otp": "654321"
  }'

Response

{
  "success": true,
  "code": 1,
  "message": "Success",
  "data": {
    "timestamp": "1666756646",
    "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.
message	string	The status or error message.
data.timestamp	int	The server timestamp.
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.

Errors

Code	Description
103	Thông tin Partner không chính xác — Partner details are incorrect.
129	Token không hợp lệ — Invalid token.
190108	Tài khoản chưa hoạt động — Account not activated.
190301	Period không chính xác — Incorrect period.
190303	Client time không chính xác — Incorrect client time.

190303 is the drift signal: the device clock is too far from the server's. Apply the returned timestamp as an offset rather than asking the user to fix their clock.

Next Steps

• Validate OTP — retry validation once the clock is reconciled
• Activate — where the same TOTP configuration is first issued