# 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:

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



{% stepper %}
{% step %}
### Generate Salt

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

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

{% step %}
### Private Key

Fill the private key into the JSON object

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

{% step %}
### Convert JSON to String

Flatten the JSON object to string.&#x20;

* ​**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.

<table><thead><tr><th width="410">JSON Object</th><th>Flat String</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{
    "requestId": "APPREQ00990320fed02000",
    "sender": "client1",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZ123da",
    "senderKey": "yourkey",
    "params": {
        "name": "Tester"
    }
}
</code></pre></td><td>"locale=en_ke&#x26;params.name=Tester&#x26;requestId=APPREQ00990320fed02000&#x26;salt=QcEwsZ123da&#x26;sender=client1&#x26;senderKey=yourKey&#x26;timestamp=1650533105687"<br></td></tr></tbody></table>
{% endstep %}

{% step %}
### Hash the string

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

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

{% step %}
### Remove senderKey

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

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



## 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.

{% hint style="warning" %}
**NOTES:** Please do remember to keep the value of the signature field of the response for comparison later.
{% endhint %}

3. Convert the modified response JSON to string with alphabetical sorting.
4. Hash the string converted from response JSON in step 3.
5. Compare the hash result from step 4 to the signature of the original response.

### Example

The original response JSON object:

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



{% stepper %}
{% step %}
### Private Key

Fill your private key to the field `senderKey`

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

{% step %}
### Remove Signature

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

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

{% step %}
### Convert JSON to String

<table><thead><tr><th width="418">JSON Object</th><th>Converted String</th></tr></thead><tbody><tr><td><pre class="language-json"><code class="lang-json">{
    "code": "00000",
    "msg": "Completed successfully",
    "requestId": "APPREQ00990320fed02000",
    "sender": "choice.baas",
    "locale": "en_KE",
    "timestamp": 1650533105687,
    "salt": "QcEwsZHMUr",
    "senderKey": "yourKey",
    "data": {
        "accountId": "46012123456789"
    }
}
</code></pre></td><td>"code=00000&#x26;data.accountId=46012123456789&#x26;locale=en_ke&#x26;msg=Completed successfully&#x26;requestId=APPREQ00990320fed02000&#x26;salt=QcEwsZ123da&#x26;sender=choice.baas&#x26;senderKey=yourKey&#x26;timestemp=1650533105687"<br></td></tr></tbody></table>
{% endstep %}

{% step %}
### Hash the converted string

Hash the converted string with SHA-256
{% endstep %}

{% step %}
### 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.
{% endstep %}
{% endstepper %}
