Authentication

To ensure the security and integrity of system communication, Choice BaaS API requires all request senders to sign the request message with their private key, and the Choice BaaS platform will verify the signature before processing.​ If the signature is invalid, the request will NOT be accepted.

Sign the Request

After onboarding, a private key can be obtained from your account manager and every request you make should be signed with it. The signing algorithm is described below:

1. Fill the salt into the request JSON object with salt field name.

2. Fill the private key into the request JSON object with senderKey field name.

3. Convert the key-value pair of the request JSON object into string with alphabetical sorting. When converting, make the key-value pair as string=string and join them with &.

4. Hash the converted string which got in step 1 with SHA-256 and the private key then fill the hashed string back to the request JSON with field name - signature.

5. Remove the senderKey field from request JSON object.

Example

The original request JSON object is:

{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "params": {
        "name": "Tester"
    }
}

1

Generate Salt

Generate the salt randomly and fill it into the request JSON object

{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZ123da",
    "params": {
        "name": "Tester"
    }
}

2

Private Key

Fill the private key into the JSON object

{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZ123da",
    "senderKey": "yourkey",
    "params": {
        "name": "Tester"
    }
}

3

Convert JSON to String

Flatten the JSON object to string.

• ​ASCII Order: Sorted by raw byte values (e.g., A (65) before a (97)).

• ​Joined with &: Uses & as the delimiter between sorted key-value pairs.

JSON Object	Flat String
{ "requestId": "APPREQ00990320fed02000", "sender": "client1", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZ123da", "senderKey": "yourkey", "params": { "name": "Tester" } }	"locale=en_ke&params.name=Tester&requestId=APPREQ00990320fed02000&salt=QcEwsZ123da&sender=client1&senderKey=yourKey&timestamp=1650533105687"

4

Hash the string

Hash the converted string with SHA-256 and fill the hashed into the field signature

{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZ123da",
    "senderKey": "yourkey",
    "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11",
    "params": {
        "name": "Tester"
    }
}

5

Remove senderKey

Remove the field senderKey from the request JSON object. Then you get the final request JSON object and send out.

{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZ123da",
    "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11",
    "params": {
        "name": "Tester"
    }
}

Verify Signature

To verify the signature of the response from Choice BaaS

1. Fill the private key into the response JSON with field name senderKey.

2. Remove the field signature field from the response JSON.

NOTES: Please do remember to keep the value of the signature field of the response for comparison later.

1. Convert the modified response JSON to string with alphabetical sorting.

2. Hash the string converted from response JSON in step 3.

3. Compare the hash result from step 4 to the signature of the original response.

Example

The original response JSON object:

{
    "code": "00000",
    "msg": "Completed successfully",
    "requestId": "APPREQ00990320fed02000",
    "sender": "choice.baas",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZHMUr",
    "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11",
    "data": {
        "accountId": "46012123456789"
    }
}

1

Private Key

Fill your private key to the field senderKey

{
    "code": "00000",
    "msg": "Completed successfully",
    "requestId": "APPREQ00990320fed02000",
    "sender": "choice.baas",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZHMUr",
    "signature": "cdfd996e7e5ca655d3fa663db03abe63b852669f04e1f82fda9b473f606a11",
    "senderKey": "yourKey",
    "data": {
        "accountId": "46012123456789"
    }
}

2

Remove Signature

Remove the field signature field from the response JSON.

{
    "code": "00000",
    "msg": "Completed successfully",
    "requestId": "APPREQ00990320fed02000",
    "sender": "choice.baas",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZHMUr",
    "senderKey": "yourKey",
    "data": {
        "accountId": "46012123456789"
    }
}

3

Convert JSON to String

JSON Object	Converted String
{ "code": "00000", "msg": "Completed successfully", "requestId": "APPREQ00990320fed02000", "sender": "choice.baas", "locale": "en_KE", "timestamp": 1650533105687, "salt": "QcEwsZHMUr", "senderKey": "yourKey", "data": { "accountId": "46012123456789" } }	"code=00000&data.accountId=46012123456789&locale=en_ke&msg=Completed successfully&requestId=APPREQ00990320fed02000&salt=QcEwsZ123da&sender=choice.baas&senderKey=yourKey&timestemp=1650533105687"

4

Hash the converted string

Hash the converted string with SHA-256

5

Compare Signatures

Compare the signature that 1. from the original response 2. from the hashed converted string. If the two are the same, then the response is valid, otherwise, it's invalid.