API Request Signature

In order to authenticate legitimate users, the Exoscale API requires incoming requests to be signed using valid Exoscale API account credentials with the following mechanism.

Signature Mechanism

The message (i.e. content) to sign contains several segments concatenated using a line return character (\n).

All segments must be included and in the described order, including empty ones depending on the context of the request (e.g. no request body).

  • Request method and request URL (path only), separated by a space character
  • Request body
  • Request URL parameters (Query String) values, concatenated without separator. The matching parameter names have to be specified in the resulting signature header signed-query-args= pragma, separated by semicolons (e.g. p1;p2;pN).
  • Request header values, concatenated without separator (none at the moment, leave empty)
  • Request expiration date in UNIX timestamp format

Example message to sign for GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2:

GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0
v1v2
1599140767

The request signature consists of the base64-encoded HMAC hash of the UTF-8 encoded message and the Exoscale API secret using the SHA265 function:

signature = BASE64_ENCODE(HMAC_SHA256(Exoscale API secret, message))

Finally, the computed signature must be added to the API request in a Authorization header such as:

Authorization: EXO2-HMAC-SHA256 credential=<Exoscale API key>,expires=<expiration date UNIX timestamp>,signature=<signature>

Example API query:

GET /v2/resource/a02baf5a-a3e4-49a0-857b-8a08d276c1c0?p1=v1&p2=v2 HTTP/1.1
Host: api-ch-gva-2.exoscale.com
Authorization: EXO2-HMAC-SHA256 credential=EXO29147e9f89102b7ac1e88514,signed-query-args=p1;p2,expires=1599140767,signature=2AOBQsbElQb4FpKT/FM/9T4NobjlmZkSGvvdUth/xlY=

Reference Implementations

You can look up the following existing reference implementations: