KMS Key

Operations for KMS Key lifecycle management.

enable-kms-key

Enable KMS Key

POST /kms-key/{id}/enable

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.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Responses

200: Key enabled

Content-Type: application/json

Property	Type	Description
`status`	string	Allowed values: `success`, `target-registered`, `already-applied`. Default: `success`.

Example output

{
  "status": "success"
}

400: 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-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for enable-kms-key: golang | Python | Java

CLI: exo api enable-kms-key

disable-kms-key

Disable KMS Key

POST /kms-key/{id}/disable

Disables a KMS Key by setting its state to “disabled”. This prevents the use of the KMS key for cryptographic and key lifecycle operations.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Responses

200: Key disabled

Content-Type: application/json

Property	Type	Description
`status`	string	Allowed values: `success`, `target-registered`, `already-applied`. Default: `success`.

Example output

{
  "status": "success"
}

400: 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-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for disable-kms-key: golang | Python | Java

CLI: exo api disable-kms-key

create-kms-key

Create KMS Key

POST /kms-key

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.

Request body

Content-Type: application/json

Property	Type	Required	Description
`name`	string	yes	A human-readable display name uniquely identifying the KMS key within the tenant space.
`description`	string	no	An optional detailed description providing additional context about the key’s intended use case.
`key-spec`	string	no	The cryptographic key specification defining the key’s algorithm and, for asymmetric keys, its curve or modulus size. Allowed values: `AES_256`, `ECC_NIST_P256`, `ECC_NIST_P384`, `ECC_NIST_P521`, `ECC_EDWARDS25519`, `RSA_3072`, `RSA_4096`, `ML_DSA_65`, `ML_DSA_87`. Default: `AES_256`.
`multi-zone`	boolean	no	True if this is a multi-zone key. Default: `false`.
`source`	string	no	Indicates the source of the key material, either generated and held within Exoscale KMS, or backed by an external key store. Allowed values: `exoscale-kms`, `external-key-store`. Default: `exoscale-kms`.
`usage`	string	no	Allowed values: `encrypt-decrypt`, `sign-verify`. Default: `encrypt-decrypt`.
`xks`	Xks Key	no

Example

{
  "description": "string",
  "key-spec": "AES_256",
  "multi-zone": true,
  "name": "string",
  "source": "exoscale-kms",
  "usage": "encrypt-decrypt",
  "xks": {
    "external-key-id": "string",
    "xks-id": "string"
  }
}

Responses

200: Created new KMS key

Content-Type: application/json

Property	Type	Description
`created-at`	string	The UTC timestamp showing when the KMS key was originally provisioned. ISO 8601 date-time.
`description`	string	An optional detailed description providing additional context about the key’s intended use case.
`id`	string	The globally unique identifier (UUID) assigned to the newly created KMS key. Must be a valid UUID.
`key-spec`	string	The cryptographic key specification used to generate the key, defining its algorithm and, for asymmetric keys, its curve or modulus size.
`multi-zone`	boolean	True if this is a multi-zone key.
`name`	string	The display name assigned to the KMS key.
`origin-zone`	string	The creation zone of the KMS key.
`revision`	Revision Stamp
`rotation`	Key Rotation Config
`source`	string	Indicates the source of the key material, either generated and held within Exoscale KMS, or backed by an external key store. Allowed values: `exoscale-kms`, `external-key-store`.
`status`	string	Allowed values: `enabled`, `disabled`, `pending-deletion`.
`status-since`	string	The timestamp indicating exactly when the current key status was last transitioned. ISO 8601 date-time.
`usage`	string	The cryptographic operation constraints allowed on this key.
`xks`	Xks Key

Example output

{
  "created-at": "2024-01-01T12:00:00Z",
  "description": "string",
  "id": "string",
  "key-spec": "string",
  "multi-zone": true,
  "name": "string",
  "origin-zone": "string",
  "revision": {
    "at": "2024-01-01T12:00:00Z",
    "seq": 0
  },
  "rotation": {
    "automatic": true,
    "manual-count": 0,
    "next-at": "2024-01-01T12:00:00Z",
    "rotation-period": 0
  },
  "source": "exoscale-kms",
  "status": "enabled",
  "status-since": "2024-01-01T12:00:00Z",
  "usage": "string",
  "xks": {
    "external-key-id": "string",
    "xks-id": "string"
  }
}

400: 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-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for create-kms-key: golang | Python | Java

CLI: exo api create-kms-key

get-kms-key

Get KMS Key

GET /kms-key/{id}

Retrieve KMS Key details.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Responses

200: KMS Key Details

Content-Type: application/json

Property	Type	Description
`created-at`	string	The UTC timestamp showing when the KMS key was originally provisioned. ISO 8601 date-time.
`delete-at`	string	ISO 8601 date-time.
`description`	string	An optional detailed description providing additional context about the key’s intended use case.
`id`	string	The globally unique identifier (UUID) of the retrieved KMS key. Must be a valid UUID.
`key-spec`	string	The cryptographic key specification used to generate the key, defining its algorithm and, for asymmetric keys, its curve or modulus size.
`material`	Key Material
`multi-zone`	boolean	True if this is a multi-zone key.
`name`	string	The display name of the KMS key.
`origin-zone`	string	The creation zone of the KMS key.
`replicas`	array[string]	A list of availability zones where this specific key has active replica mirrors.
`replicas-status`	array of Replica State	Detailed synchronization metrics for each regional replica mirror.
`revision`	Revision Stamp
`rotation`	Key Rotation Config
`source`	string	Indicates the source of the key material, either generated and held within Exoscale KMS, or backed by an external key store. Allowed values: `exoscale-kms`, `external-key-store`.
`status`	string	Allowed values: `enabled`, `disabled`, `pending-deletion`.
`status-since`	string	The timestamp indicating exactly when the current key status was last transitioned. ISO 8601 date-time.
`usage`	string	The cryptographic operation constraints allowed on this key.
`xks`	Xks Key

Example output

{
  "created-at": "2024-01-01T12:00:00Z",
  "delete-at": "2024-01-01T12:00:00Z",
  "description": "string",
  "id": "string",
  "key-spec": "string",
  "material": {
    "automatic": true,
    "created-at": "2024-01-01T12:00:00Z",
    "version": 0
  },
  "multi-zone": true,
  "name": "string",
  "origin-zone": "string",
  "replicas": [
    "string"
  ],
  "replicas-status": [
    {
      "last-applied-watermark": 0,
      "last-failure": {
        "attempted-watermark": 0,
        "error": "string",
        "failed-at": "2024-01-01T12:00:00Z"
      },
      "zone": "string"
    }
  ],
  "revision": {
    "at": "2024-01-01T12:00:00Z",
    "seq": 0
  },
  "rotation": {
    "automatic": true,
    "manual-count": 0,
    "next-at": "2024-01-01T12:00:00Z",
    "rotation-period": 0
  },
  "source": "exoscale-kms",
  "status": "enabled",
  "status-since": "2024-01-01T12:00:00Z",
  "usage": "string",
  "xks": {
    "external-key-id": "string",
    "xks-id": "string"
  }
}

400: Errors

Key Not Found: The request was rejected because the specified KMS Key could not be found.

Content-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for get-kms-key: golang | Python | Java

CLI: exo api get-kms-key

disable-kms-key-rotation

Disable Key Rotation

POST /kms-key/{id}/disable-key-rotation

Disable the periodic rotation of a KMS Key.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Responses

200: Key rotation disabled

Content-Type: application/json

Property	Type	Description
`rotation`	Key Rotation Config

Example output

{
  "rotation": {
    "automatic": true,
    "manual-count": 0,
    "next-at": "2024-01-01T12:00:00Z",
    "rotation-period": 0
  }
}

400: 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 rejected 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-Type: application/json

Property	Type	Description
`detail`	string	A highly contextual, readable explanation breaking down explicitly what triggered this error scenario.
`status`	integer	Min: `100`. Max: `599`.
`title`	string	A brief summary defining the class of failure, optimal for quick user interface groupings.
`type`	string	An absolute or relative URI reference pointing to human-readable documentation concerning the specific problem type encountered. Must be a valid URI reference.
`xks-proxy-error`	Xks Proxy Error Detail

Example output

{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string",
  "xks-proxy-error": {
    "error-message": "string",
    "error-name": "string"
  }
}

SDK reference for disable-kms-key-rotation: golang | Python | Java

CLI: exo api disable-kms-key-rotation

enable-kms-key-rotation

Enable Key Rotation

POST /kms-key/{id}/enable-key-rotation

Enable the periodic rotation of a KMS Key.

Path parameters

Name	In	Description
`id`	`path`	Must be a valid UUID.

Request body

Content-Type: application/json

Property	Type	Required	Description
`rotation-period`	integer	no	The number of days between each automatic key rotation. Min: `90`. Max: `2560`. Default: `365`.

Example

{
  "rotation-period": 0
}

Responses

200: Periodic key rotation enabled

Content-Type: application/json

Property	Type	Description
`rotation`	Key Rotation Config

Example output

{
  "rotation": {
    "automatic": true,
    "manual-count": 0,
    "next-at": "2024-01-01T12:00:00Z",
    "rotation-period": 0
  }
}