Response signature

What is it?

Response signing is a feature introduced to ensure the veracity of the information received from our API when it needs to be transmitted through a device you do not control (such as your customer's cell phone, for example).

When use it?

The functionality to sign requests is optional, and if you are integrating directly on your backend, there is no need to use it.

However, if you intend to make requests for our API from an application that does not run on a device you control, we strongly recommend that you sign your requests and always check your server for signing.

How does it work?

When you enable this functionality in your requests, we will no longer send the response in JSON format. The body response will become a JWT signing using the clientSecret of your token. In the payload of this JWT will be the body of the response, with all the fields that it would return if the response was not signed.

How does this ensure the authenticity of the information?

It’s simple! If an attacker modifies the response body (for example, say that his photo passed on the face liveness), this change would break the JWT signature, and you would be able to detect this in your backend, blocking its access to your system.

How to request that a response be signed?

Simply send the value true to the query string parameter shouldSingResponse in your request on routes that support the feature.

You can check whether the route supports the signature response by checking the general information on the route page.

Examples

Request example:

Note the ?shouldSignResponse=true at the end of the URL.

curl --location \
    --request POST 'api.mobile.combateafraude.com/faces/liveness?shouldSignResponse=true' \
    --header 'Authorization: {token}' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "imageUrl": "https://images.generated.photos/DQ4EKrAPT-e5slG3cXmSw20uJ2AwwhOzJeVnpI9tlMA/rs:fit:512:512/Z3M6Ly9nZW5lcmF0/ZWQtcGhvdG9zLzA5/OTk4MDcuanBn.jpg"
    }'

Response example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXF1ZXN0SWQiOiJiZjk0MDNmZi05OTQwLTQ4NDYtYjRlZi04NDE2NjJmNTIxMzkiLCJpc0FsaXZlIjpmYWxzZSwiaWF0IjoxNTk0OTI1MDgwfQ.8EOm5MomxUA5WEkgdi5E_hppNG3dSpXXsHAldTjpo2s

The JWT above was signed using the clientSecret of the {token} sent in the request.

If we extract the payload from the JWT above, we get the following JSON:

{
    "requestId": "bf9403ff-9940-4846-b4ef-841662f52139",
    "isAlive": false,
    "iat": 1594925080
}

If any field in the payload is changed, the signature breaks and you are able to detect the change in your backend.