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. For cases where a segment doesn't fit the context of the request (e.g. no request body) an empty line must be used instead.

  • 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



The two blank lines above are due to the absence of a request body and signed headers.

Example message to create a security group

POST /v2/security-group
{"name": "my-security-group"}


The two blank lines above are due to the absence of query parameters and signed headers.

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: