Signed Request

Application Signed Request

In production environments, we strongly recommend using more secure application signed requests over basic authentication.

The following pseudocode example and table demonstrates and explains how to sign a request for the Sinch platform. The result of this should be included in the HTTP Authorization header sent with the HTTP request.

Copy

Copied

    Content-MD5 = Base64 ( MD5 ( UTF8 ( [BODY] ) ) )

    Scheme = "Application"

    Signature = Base64 ( HMAC-SHA256 ( Base64-Decode ( ApplicationSecret ), UTF8 ( StringToSign ) ) );

    StringToSign = HTTP-Verb + "\n" +
                   Content-MD5 + "\n" +
                   Content-Type + "\n" +
                   CanonicalizedHeaders + "\n" +
                   CanonicalizedResource;

    Authorization = Scheme + " " + ApplicationKey + ":" + Signature

Pseudocode Component	Description
`CanonicalizedHeaders`	The only required header is `x-timestamp`.
`CanonicalizedResource`	The path to the API resource. For example, `verification/v1/verifications`.
`ApplicationKey`	The key for your Voice application found on your dashboard.
`ApplicationSecret`	The secret for your Voice application found on your dashboard. Important!: The Application Secret value must be base64-decoded from before it's used for signing.

Example of an application signed request

For the following POST request to the protected resource /v1/lookups,

Copy

Copied

    POST /v1/lookups
    x-timestamp: 2014-06-04T13:41:58Z
    Content-Type: application/json

    "number": "+46700000000"

the signature should be formed like this:

Copy

Copied

    Content-MD5 = Base64 ( MD5 ( UTF8 ( [BODY] ) ) )
        jANzQ+rgAHyf1MWQFSwvYw==

    StringToSign
    POST
    jANzQ+rgAHyf1MWQFSwvYw==
    application/json
    x-timestamp:2014-06-04T13:41:58Z
    /verification/v1/verifications

    Signature = Base64 ( HMAC-SHA256 ( Base64-Decode ( ApplicationSecret ), UTF8 ( StringToSign ) ) )
        qDXMwzfaxCRS849c/2R0hg0nphgdHciTo7OdM6MsdnM=

    HTTP Authorization Header Authorization: Application
        5F5C418A0F914BBC8234A9BF5EDDAD97:qDXMwzfaxCRS849c/2R0hg0nphgdHciTo7OdM6MsdnM=

Note

For requests that don’t contain a body (like GET requests) or requests where the body is empty, the Content-MD5 value of StringToSign should be left empty, as in the following example:

Copy

Copied

    StringToSign = HTTP-Verb + "\n" +
        "\n" +
        Content-Type + "\n" +
        CanonicalizedHeaders + "\n" +
        CanonicalizedResource;

Timestamp

The client must send a custom header x-timestamp (time) with each request that's validated by the server. This custom header is used to determine that the request is not too old. The timestamp is also part of the signature. The timestamp must be formatted to ISO 8061 specifications.

Important!

The timestamp must be in the Coordinated Universal Time (UTC) timezone.

Example

Copy

Copied

x-timestamp: 2014-06-02T15:39:31.2729234Z