SmartClean HMAC Signature Version 1
The Authorization header must contain a string with format as shown below:
SCHMAC_V1;<access_key>;<signature>
Obtaining HMAC credentials
You must have received the HMAC credentials for your property, containing the accesskey and secretkey.
Please share the credentials with trusted entities only and ensure the secret is rotated or key inactivated when not in use.
Signing requests (Generating the signature)
Each request in Matrix is generally represented as:
https://console.smartclean.io/prod/v2/<module>/<version>/actions?op=<op>&propid=<propid>&pid=<pid>&org=<org>
| Parameter | Description |
|---|---|
| op | The operation being performed. |
| propid | The property id. |
| org | The organisation id. |
| pid | The building id (send as scnoop if not required). |
| module | The module being accessed. |
| version | The version of API for the module being accessed. |
Consider a request to be signed at epoch time 1631346630 for module attendance having op as scattendance.readIntegration.
Assuming the access key as dummyaccesskey/abcd (alias apiuser) and associated secret key as mydummysecretkey for propert with id propid, the signing key for:
SCHMAC("v1", "attendance", "scattendance.readIntegration", "1631346630", "mydummysecretkey", "propid")
must be <module>/<propid>/<op>/<access key>/<epoch time sent in header> = attendance/propid/scattendance.readIntegration/dummyaccesskey/abcd/1631346630
generating the signed value as:
5f7a71f6ae877c13954c8a70a485ac656bfa5f7cdd1417866660c8e5198d9bf5
The final value to be sent in Authorization header is then:
SCHMAC_V1;<access_key>;<signature> = SCHMAC_V1;dummyaccesskey/abcd;5f7a71f6ae877c13954c8a70a485ac656bfa5f7cdd1417866660c8e5198d9bf5
Along with additional headers:
| x-sc-time | 1631346630 |
Note that the server allows a maximum clock skew of 300s (5 minutes).
The following helper python script can be used to verify the signatures generated by different implementations.
import hmac, hashlib, time
etime = str(int(time.time()))
secret_key = b"mydummysecretkey"
access_key = "dummyaccesskey/abcd"
op = "scattendance.readIntegration"
propid = "propid"
module = "attendance"
total_paramsStr = module + '/' + propid + '/' + op + '/' + access_key + '/' + etime
total_params = bytes(total_paramsStr, "utf-8")
signature = hmac.new(secret_key, total_params, hashlib.sha256).hexdigest()
print("signature = {0}".format(signature))