openapi: 3.0.0 info: version: 2.0.0 termsOfService: https://exoscale.com/terms contact: email: support@exoscale.com name: Exoscale Support url: https://portal.exoscale.com/tickets title: Exoscale ai-api-key event API description: Infrastructure automation API, allowing programmatic access to all Exoscale products and services. servers: - url: https://api-{zone}.exoscale.com/v2 variables: zone: default: ch-gva-2 enum: - ch-gva-2 - ch-dk-2 - de-fra-1 - de-muc-1 - at-vie-1 - at-vie-2 - bg-sof-1 - hr-zag-1 tags: - description: "Events form the basis of the Exoscale audit-trail, a mechanism\n to query past events performing mutations on resources\n which happened on an organization." parent: audit-trail externalDocs: description: Read more url: https://community.exoscale.com/platform/audit-trail/ name: event x-display-name: Event x-weight: 1010 x-icon: exo-license paths: /event: get: tags: - event responses: '200': description: '200' content: application/json: schema: type: array items: $ref: '#/components/schemas/event' description: "Retrieve Mutation Events for a given date range. Defaults to retrieving Events for the past 24 hours.\n Both a `from` and `to` arguments can be specified to filter Events over a specific period.\n Events will be the the most descriptive possible but not all fields are mandatory" parameters: - in: query required: false name: from schema: type: string format: date-time - in: query required: false name: to schema: type: string format: date-time summary: List Events operationId: list-events components: schemas: user: type: object properties: sso: type: boolean description: SSO enabled two-factor-authentication: type: boolean description: Two Factor Authentication enabled email: type: string readOnly: true description: User Email id: type: string format: uuid readOnly: true description: User ID role: $ref: '#/components/schemas/iam-role' description: IAM Role pending: type: boolean readOnly: true description: True if the user has not yet created an Exoscale account required: - email - role description: User iam-service-policy-rule: type: object properties: action: type: string enum: - allow - deny expression: type: string resources: type: array items: type: string labels: type: object additionalProperties: type: string iam-api-key: type: object properties: name: type: string x-go-findable: '1' description: IAM API Key name key: type: string x-go-findable: '2' description: IAM API Key role-id: type: string format: uuid description: IAM API Key Role ID description: IAM API Key iam-role: type: object properties: description: type: string maxLength: 255 minLength: 1 description: IAM Role description labels: $ref: '#/components/schemas/labels' description: IAM Role Labels permissions: type: array items: type: string enum: - bypass-governance-retention - reset-iam-organization-policy uniqueItems: true description: IAM Role permissions assume-role-policy: $ref: '#/components/schemas/iam-policy' description: IAM Assume Role Policy editable: type: boolean description: IAM Role mutability name: type: string maxLength: 255 minLength: 1 description: IAM Role name max-session-ttl: type: integer format: int64 minimum: 0 exclusiveMinimum: true description: Maximum TTL requester is allowed to ask for when assuming a role policy: $ref: '#/components/schemas/iam-policy' description: IAM Role Policy id: type: string format: uuid readOnly: true description: IAM Role ID description: IAM Role event: type: object properties: iam-user: $ref: '#/components/schemas/user' description: Details about the IAM User request-id: type: string description: Operation unique identifier iam-role: $ref: '#/components/schemas/iam-role' description: Details about the IAM Role zone: type: string description: Operation targeted zone get-params: type: object description: Query string parameters (free form map) body-params: type: object description: Body parameters (free form map) status: type: integer format: int64 minimum: 0 exclusiveMinimum: true description: Operation HTTP status source-ip: type: string description: Client IP address iam-api-key: $ref: '#/components/schemas/iam-api-key' description: Details about the IAM API Key uri: type: string description: Operation request URI elapsed-ms: type: integer format: int64 minimum: 0 exclusiveMinimum: true description: Operation processing time timestamp: type: string format: date-time description: Time at which the event happened, millisecond resolution path-params: type: object description: URI path parameters (free form map) handler: type: string description: Operation handler name message: type: string description: Operation message description: A notable Mutation Event which happened on the infrastructure iam-policy: type: object properties: default-service-strategy: type: string enum: - allow - deny description: IAM default service strategy services: type: object additionalProperties: $ref: '#/components/schemas/iam-service-policy' description: IAM services required: - default-service-strategy - services description: Policy iam-service-policy: type: object properties: type: type: string enum: - rules - allow - deny rules: type: array items: $ref: '#/components/schemas/iam-service-policy-rule' x-topics: - title: API Request Signature content: ' 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 v1v2 1599140767 ``` The two blank lines above are due to the absence of a request body and signed headers. Example *message* to [create a security group](https://community.exoscale.com/reference/api/compute/security-group/#create-security-group) ``` POST /v2/security-group {"name": "my-security-group"} 1599140767 ``` 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](https://en.wikipedia.org/wiki/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=,expires=,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: * Go: [github.com/exoscale/egoscale/api/v2 > `SecurityProviderExoscale.signRequest`](https://github.com/exoscale/egoscale/blob/master/v2/api/security.go) * Python: [requests-exoscale-auth > `ExoscaleV2Auth`](https://github.com/exoscale/requests-exoscale-auth/blob/master/exoscale_auth.py) ' - title: Zone local resources content: ' The API is deployed across all Exoscale zones. 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 for each zone. '