Exoscale Public API

Infrastructure automation API, allowing programmatic access to all Exoscale products and services.

The OpenAPI Specification source of this documentation can be obtained here:

This is the documentation for version 2.0.0 of the API. Last update on Mar 8, 2023.

Base URL

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

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:

Zone local resources

The API is deployed across multiple zones: ch-gva-2, ch-dk-2, de-fra-1, de-muc-1, at-vie-1, bg-sof-1. When performing a compute call, you should use the relevant zone for your resource.
For example: https://api-de-fra-1.exoscale.com/v2/instance would return only the instances from de-fra-1, https://api-ch-gva-2.exoscale.com/v2/instance from ch-gva-2.
To obtain a list of all instances across all zones, you would need to do the corresponding request per zone.

Note that if no zone is specified during the call ch-gva-2 will be used by default.