Exoscale Kms Key API
Operations for KMS Key lifecycle management.
Operations for KMS Key lifecycle management.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/exoscale:exoscale-kms-key-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.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 Kms Key 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: Operations for KMS Key lifecycle management.
parent: kms
externalDocs:
description: Read more
url: https://community.exoscale.com/documentation/security/kms/overview
name: kms-key
x-display-name: KMS Key
x-weight: 1130
x-icon: exo-license
paths:
/kms-key/{id}/disable-key-rotation:
post:
tags:
- kms-key
responses:
'200':
description: Key rotation disabled
content:
application/json:
schema:
$ref: '#/components/schemas/disable-kms-key-rotation-response'
'400':
description: '### Errors
Invalid Origin: The request was rejected because automatic key rotation can only be enabled on a KMS key with origin "exoscale-kms".
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Not on Default: The request was rejected because the operation is not allowed on the default key.
Not on Replica: The request was rejectde because the operation is not allowed on a replica.
Key is Pending Deletion: The request was rejected because it was performed on a key that is pending deletion.
Key is Disabled: The request was rejected because the specified KMS key is disabled.
Invalid Usage: The request was rejected because the operation is only allowed on symmetric keys with usage "encrypt-decrypt".
Conflict: The request was rejected because the automatic rotation is already enabled for this KMS Key.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Disable the periodic rotation of a KMS Key.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Disable Key Rotation
operationId: disable-kms-key-rotation
/kms-key/{id}:
get:
tags:
- kms-key
responses:
'200':
description: KMS Key Details
content:
application/json:
schema:
$ref: '#/components/schemas/get-kms-key-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Retrieve KMS Key details.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Get KMS Key
operationId: get-kms-key
/kms-key/{id}/enable:
post:
tags:
- kms-key
responses:
'200':
description: Key enabled
content:
application/json:
schema:
$ref: '#/components/schemas/success-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Key is Pending Deletion: The request was rejected because it was performed on a key that is pending deletion.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Enables a KMS Key by setting its state to "enabled". It restores the ability to fully use the KMS key for cryptographic operations and key lifecycle operations.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Enable KMS Key
operationId: enable-kms-key
/kms-key/{id}/list-key-rotations:
get:
tags:
- kms-key
responses:
'200':
description: The list of all historical rotations for the requested KMS key.
content:
application/json:
schema:
$ref: '#/components/schemas/list-kms-key-rotations-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: List all the key material versions of a KMS Key.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: List KMS Key Rotations
operationId: list-kms-key-rotations
/kms-key/{id}/enable-key-rotation:
post:
tags:
- kms-key
responses:
'200':
description: Periodic key rotation enabled
content:
application/json:
schema:
$ref: '#/components/schemas/enable-kms-key-rotation-response'
'400':
description: '### Errors
Invalid Origin: The request was rejected because automatic key rotation can only be enabled on a KMS key with origin "exoscale-kms".
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Not on Default: The request was rejected because the operation is not allowed on the default key.
Not on Replica: The request was rejectde because the operation is not allowed on a replica.
Key is Pending Deletion: The request was rejected because it was performed on a key that is pending deletion.
Key is Disabled: The request was rejected because the specified KMS key is disabled.
Invalid Usage: The request was rejected because the operation is only allowed on symmetric keys with usage "encrypt-decrypt".
Conflict: The request was rejected because the automatic rotation is already enabled for this KMS Key.
Bad Request: The request was rejected because of an invalid request body or path parameter.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Enable the periodic rotation of a KMS Key.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Enable Key Rotation
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/enable-kms-key-rotation-request'
operationId: enable-kms-key-rotation
/kms-key/{id}/rotate:
post:
tags:
- kms-key
responses:
'200':
description: Key rotated
content:
application/json:
schema:
$ref: '#/components/schemas/rotate-kms-key-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Key is Pending Deletion: The request was rejected because it was performed on a key that is pending deletion.
Not on a Replica: The request was rejected because the operation is not allowed on a replica.
Invalid Usage: The request was rejected because the operation is only allowed on symmetric keys with usage "encrypt-decrypt".
Key is Disabled: The request was rejected because the specified KMS key is disabled.
Manual Rotation Limit: The request was rejected because you reached your limit of 10 manual rotations per key for this KMS key.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Performs an immediate rotation of the key material for a symmetric key.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Rotate Key
operationId: rotate-kms-key
/kms-key/{id}/disable:
post:
tags:
- kms-key
responses:
'200':
description: Key disabled
content:
application/json:
schema:
$ref: '#/components/schemas/success-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Key is Pending Deletion: The request was rejected because it was performed on a key that is pending deletion.
Not on Default: The request was rejected because the operation is not allowed on the default key.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Disables a KMS Key by setting its state to "disabled". This prevents the use of the KMS key for cryptographic and key lifecycle operations.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Disable KMS Key
operationId: disable-kms-key
/kms-key:
post:
tags:
- kms-key
responses:
'200':
description: Created new KMS key
content:
application/json:
schema:
$ref: '#/components/schemas/create-kms-key-response'
'400':
description: '### Errors
Name Conflict: The request was rejected because a key with the same name already exists in the target zone.
Bad Request: The request was rejected because of an invalid request body or path parameter.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Create a customer-managed unique KMS Key in your organization. A KMS Key is a logical representation of a cryptographic key material. It also includes metadata such as a UUID, a name and its state.
parameters: []
summary: Create KMS Key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create-kms-key-request'
operationId: create-kms-key
get:
tags:
- kms-key
responses:
'200':
description: A list of all KMS keys in the target zone
content:
application/json:
schema:
$ref: '#/components/schemas/list-kms-keys-response'
'400':
description: '### Errors
Bad Request: The request was rejected because of an invalid request body or path parameter.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Lists all KMS Keys in your organization in a given zone.
parameters: []
summary: List KMS Keys
operationId: list-kms-keys
/kms-key/{id}/schedule-deletion:
post:
tags:
- kms-key
responses:
'200':
description: Key deletion scheduled
content:
application/json:
schema:
$ref: '#/components/schemas/schedule-kms-key-deletion-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Not on Default: The request was rejected because the operation is not allowed on the default key.
Not on Replica: The request was rejectde because the operation is not allowed on a replica.
Bad Request: The request was rejected because of an invalid request body or path parameter.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Schedules a KMS key for deletion after a delay. You can specify a delay of 7-30 days.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Schedule KMS Key Deletion
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/schedule-kms-key-deletion-request'
operationId: schedule-kms-key-deletion
/kms-key/{id}/replicate:
post:
tags:
- kms-key
responses:
'200':
description: Key replication target registered
content:
application/json:
schema:
$ref: '#/components/schemas/success-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Key is Pending Deletion: The request was rejected because it was performed on a key that is pending deletion.
Not on Default: The request was rejected because the operation is not allowed on the default key.
Not Multizone: The request was rejected because the KMS key is not a multi-zone key.
Conflict: The request was rejected because the key is already replicated in the target zone.
Invalid Argument: The request was rejected because the target zone is invalid.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Replicate a KMS key to a target zone.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Replicate KMS Key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/replicate-kms-key-request'
operationId: replicate-kms-key
/kms-key/{id}/cancel-deletion:
post:
tags:
- kms-key
responses:
'200':
description: Key deletion cancelled
content:
application/json:
schema:
$ref: '#/components/schemas/success-response'
'400':
description: '### Errors
Key Not Found: The request was rejected because the specified KMS Key could not be found.
Not on Replica: The request was rejectde because the operation is not allowed on a replica.
Not Pending Deletion: The request was rejected because the key is not pending deletion.
'
content:
application/json:
schema:
$ref: '#/components/schemas/error-response'
description: Cancels the scheduled deletion of a KMS Key.
parameters:
- in: path
required: true
name: id
schema:
type: string
format: uuid
summary: Cancel KMS Key Deletion
operationId: cancel-kms-key-deletion
components:
schemas:
schedule-kms-key-deletion-response:
type: object
properties:
delete-at:
type: string
description: Timestamp of the key deletion
format: date-time
replica-failure:
type: object
required:
- attempted-watermark
- error
- failed-at
properties:
attempted-watermark:
type: integer
description: The target sync sequence watermark that triggered the replication failure.
error:
type: string
description: A descriptive message containing error logs or system details regarding the sync failure.
failed-at:
type: string
format: date-time
description: The UTC timestamp showing exactly when the replication sync window failed.
rotate-kms-key-response:
type: object
required:
- rotation
properties:
rotation:
$ref: '#/components/schemas/key-rotation-config'
success-response:
type: object
required:
- status
properties:
status:
type: string
enum:
- success
- target-registered
- already-applied
default: success
revision-stamp:
type: object
required:
- at
- seq
properties:
at:
type: string
format: date-time
description: The timestamp recording exactly when this specific revision iteration occurred.
seq:
type: integer
minimum: 0
description: Monotonically increasing sequencing value utilized for optimistic concurrency control locks.
list-kms-key-rotations-response-entry:
type: object
required:
- version
- rotated-at
- automatic
properties:
version:
type: integer
description: The absolute increment index referencing this specific historical structural material setup.
rotated-at:
type: string
format: date-time
description: The UTC timestamp tracking precisely when this historical adjustment pass finished processing.
automatic:
type: boolean
description: Flag stating whether an automation run handled this historic mutation or if manual actor keys initiated it.
replica-state:
type: object
required:
- zone
- last-applied-watermark
properties:
zone:
type: string
description: The destination target zone tracking this specific replica instance.
last-applied-watermark:
type: integer
description: The latest logical sequence number or state watermark successfully synced to this regional replica.
last-failure:
$ref: '#/components/schemas/replica-failure'
create-kms-key-response:
type: object
required:
- id
- name
- usage
- source
- status
- status-since
- multi-zone
- origin-zone
- created-at
- revision
properties:
description:
type: string
description: An optional detailed description providing additional context about the key's intended use case.
revision:
$ref: '#/components/schemas/revision-stamp'
name:
type: string
description: The display name assigned to the KMS key.
multi-zone:
type: boolean
description: True if this is a multi-zone key.
source:
type: string
enum:
- exoscale-kms
usage:
type: string
description: The cryptographic operation constraints allowed on this key.
status:
type: string
enum:
- enabled
- disabled
- pending-deletion
status-since:
type: string
format: date-time
description: The timestamp indicating exactly when the current key status was last transitioned.
id:
type: string
format: uuid
description: The globally unique identifier (UUID) assigned to the newly created KMS key.
origin-zone:
type: string
description: The creation zone of the KMS key.
created-at:
type: string
format: date-time
description: The UTC timestamp showing when the KMS key was originally provisioned.
disable-kms-key-rotation-response:
type: object
required:
- rotation
properties:
rotation:
$ref: '#/components/schemas/key-rotation-config'
list-kms-keys-response-entry:
type: object
required:
- id
- name
- usage
- source
- status
- status-since
- material
- rotation
- multi-zone
- origin-zone
- created-at
- revision
properties:
description:
type: string
description: An optional detailed description providing additional context about the key's intended use case.
rotation:
$ref: '#/components/schemas/key-rotation-config'
revision:
$ref: '#/components/schemas/revision-stamp'
delete-at:
type: string
format: date-time
name:
type: string
description: The display name of the KMS key.
multi-zone:
type: boolean
description: True if this is a multi-zone key.
source:
type: string
enum:
- exoscale-kms
usage:
type: string
description: The cryptographic operation constraints allowed on this key.
status:
type: string
enum:
- enabled
- disabled
- pending-deletion
status-since:
type: string
format: date-time
description: The precise time when the key entered its current configuration phase.
id:
type: string
format: uuid
description: The globally unique identifier (UUID) tracking this key entity.
replicas:
type: array
items:
type: string
description: Array tracking target zones currently maintaining copies of this item.
material:
$ref: '#/components/schemas/key-material'
origin-zone:
type: string
description: The creation zone of the KMS key.
created-at:
type: string
format: date-time
description: The UTC timestamp showing when the KMS key was originally provisioned.
enable-kms-key-rotation-response:
type: object
required:
- rotation
properties:
rotation:
$ref: '#/components/schemas/key-rotation-config'
enable-kms-key-rotation-request:
type: object
properties:
rotation-period:
type: integer
minimum: 90
maximum: 2560
default: 365
description: The number of days between each automatic key rotation.
replicate-kms-key-request:
type: object
required:
- zone
properties:
zone:
description: The targeted cloud zone where the KMS key should be replicated.
type: string
key-rotation-config:
type: object
required:
- manual-count
- automatic
- rotation-period
- next-at
properties:
manual-count:
type: integer
description: Total running tally of manual key rotation tasks executed by users over this key resource's lifecycle.
automatic:
type: boolean
description: When set to true, dictates that the system automatically rotates material periodically.
rotation-period:
type: integer
description: The set frequency period (measured in days) for triggers monitoring auto-rotation loops.
next-at:
type: string
format: date-time
description: Scheduled deadline calculation pinpointing the next automated rotational iteration target date.
key-material:
type: object
required:
- version
- created-at
- automatic
properties:
version:
type: integer
description: The incremental index tracing internal key rotation cycles for the key material.
created-at:
type: string
format: date-time
description: The UTC date-time indicating when this particular generation of physical cryptographic material was seeded.
automatic:
type: boolean
description: A boolean flag indicating whether this specific material version was created during an automated system rotation window.
list-kms-keys-response:
type: object
required:
- kms-keys
properties:
kms-keys:
type: array
items:
$ref: '#/components/schemas/list-kms-keys-response-entry'
description: An array containing metadata entries for all available keys for your organization in the requested zone.
create-kms-key-request:
type: object
required:
- name
properties:
name:
type: string
description: A human-readable display name uniquely identifying the KMS key within the tenant space.
description:
type: string
description: An optional detailed description providing additional context about the key's intended use case.
usage:
type: string
enum:
- encrypt-decrypt
default: encrypt-decrypt
multi-zone:
type: boolean
default: false
description: True if this is a multi-zone key.
list-kms-key-rotations-response:
type: object
required:
- rotations
properties:
rotations:
type: array
items:
$ref: '#/components/schemas/list-kms-key-rotations-response-entry'
description: A chronologically ordered collection tracking historical rotation lifecycle occurrences for this resource.
error-response:
type: object
description: RFC 9457 Problem Details error response
required:
- type
- title
- status
- detail
properties:
type:
type: string
format: uri-reference
description: An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered.
title:
type: string
description: A brief summary defining the class of failure, optimal for quick user interface groupings.
status:
type: integer
minimum: 100
maximum: 599
detail:
type: string
description: A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
schedule-kms-key-deletion-request:
type: object
properties:
delay-days:
type: integer
description: Number of days to wait until deletion is final.
minimum: 7
maximum: 30
default: 30
get-kms-key-response:
type: object
required:
- id
- name
- usage
- source
- status
- status-since
- material
- rotation
- multi-zone
- origin-zone
- created-at
- revision
properties:
description:
type: string
description: An optional detailed description providing additional context about the key's intended use case.
rotation:
$ref: '#/components/schemas/key-rotation-config'
revision:
$ref: '#/components/schemas/revision-stamp'
delete-at:
type: string
format: date-time
name:
type: string
description: The display name of the KMS key.
multi-zone:
type: boolean
description: True if this is a multi-zone key.
source:
type: string
enum:
- exoscale-kms
usage:
type: string
description: The cryptographic operation constraints allowed on this key.
replicas-status:
type: array
items:
$ref: '#/components/schemas/replica-state'
description: Detailed synchronization metrics for each regional replica mirror.
status:
type: string
enum:
- enabled
- disabled
- pending-deletion
status-since:
type: string
format: date-time
description: The timestamp indicating exactly when the current key status was last transitioned.
id:
type: string
format: uuid
description: The globally unique identifier (UUID) of the retrieved KMS key.
replicas:
type: array
items:
type: string
description: A list of availability zones where this specific key has active replica mirrors.
material:
$ref: '#/components/schemas/key-material'
origin-zone:
type: string
description: The creation zone of the KMS key.
created-at:
type: string
format: date-time
description: The UTC timestamp showing when the KMS key was originally provisioned.
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=<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:
* 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)
'
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/exoscale/openapi/exoscale-kms-key-api-openapi.yml