Operate an External Key Store

Private Preview

External Key Store (XKS) is currently available as a private preview. Review the service boundaries for current limitations and SLA status.

Monitor the Health of a Key Store

exo api get-key-store <key-store-uuid> --zone <zone-name>

Exoscale KMS checks every connected key store every 10 minutes. After an unhealthy result, it checks again after 1, 2 and 4 minutes. Once a periodic check has completed, the response includes a health object:

Field	Description
`status`	`healthy`, `unhealthy` or `unknown`
`status-reason`	The reason for the status, see the table below
`checked-at`	The time of the latest completed check
`metadata-json`	The Base64 encoded response of the proxy health endpoint, when the check succeeded
`error-detail`	A short description of the failure, when the check failed

`status-reason`	Meaning
`active`	The proxy answered the health request with a valid response.
`timeout`	The proxy did not answer in time.
`transport_error`	The connection to the proxy failed, for example because of DNS, network or TLS issues.
`credential_error`	The proxy rejected the request signature. Check the access key, the secret key and the region configured in the proxy.
`key_store_unavailable`	The proxy reported that it cannot serve requests in its current state.
`http_error`	The proxy returned another error response.

A key store is healthy as soon as the proxy answers the health request with a valid response. Details about the key managers behind the proxy, such as a degraded instance, are available in metadata-json and do not change the status.

Update a Key Store

You can change the description, the proxy endpoint and the proxy credentials. All fields are optional, and the access key and secret key must be provided together. Changing the description has no effect on the proxy connection.

Change the Proxy Endpoint

The key store must be disconnected while you change its endpoint. While it is disconnected, cryptographic operations on its KMS keys are rejected, so plan the change for a time when this interruption is acceptable.

Disconnect the key store:

exo api disconnect-key-store <key-store-uuid> --zone <zone-name>

Update the endpoint:
```
exo api update-key-store <key-store-uuid> --zone <zone-name> <<< '{
  "proxy": {
    "endpoint": "https://xks-new.example.com/kms/xks/v1"
  }
}'
```
Exoscale KMS runs a health check against the new endpoint with the current credentials, and only saves the endpoint if the check succeeds. The proxy at the new endpoint must already be running and accept the current credentials.
Connect the key store again. It does not reconnect on its own:
```
exo api connect-key-store <key-store-uuid> --zone <zone-name>
```

To change the endpoint and the credentials together, follow these steps and include both in the update.

Rotate the Proxy Credentials

You can rotate the proxy credentials while the key store stays connected.

Configure the new access key and secret key on your proxy. Keep the old credentials valid for now: Exoscale KMS signs requests with them until the update succeeds.
Update the key store with the new credentials:
```
exo api update-key-store <key-store-uuid> --zone <zone-name> <<< '{
  "proxy": {
    "auth": {
      "key": "<new-proxy-access-key>",
      "secret": "<new-proxy-secret-key>"
    }
  }
}'
```
Exoscale KMS runs a health check with the new credentials before it saves them. If your proxy does not accept them yet, the check fails, the update is rejected and the key store keeps its current credentials.
Once the update succeeds, remove the old credentials from your proxy.

If an update is rejected, see Troubleshoot an External Key Store.

Delete a Key Store

exo api delete-key-store <key-store-uuid> --zone <zone-name>

A key store can only be deleted when no KMS key references it. A key that is scheduled for deletion still references the key store until its waiting period ends. See Schedule the Deletion of a KMS Key.

Unlike KMS keys, a key store is deleted immediately, without a waiting period. Your proxy and your external keys are not affected.

Last updated on October 22, 2026