---
title: "External Key Store"
description: ""
url: https://community.exoscale.com/reference/api/kms/external-key-store/
section: reference
last_updated: 2026-10-01
---
> For AI agents: the documentation index is at https://community.exoscale.com/llms.txt. Every page is available as markdown at `<page URL>index.md` or with `Accept: text/markdown`.

# External Key Store

<style>
  span[class^="pill-"] {
    color: white;
    padding: 2px 12px;
    border-radius: 12px;
    font-size: 0.6em;
    vertical-align: middle;
    margin-right: 12px;
    font-family: sans-serif;
    font-weight: bold;
    display: inline-block;
    line-height: 1;
  }
  span.pill-GET { background-color: #61affe; }
  span.pill-POST { background-color: #49cc90; }
  span.pill-PUT { background-color: #fca130; }
  span.pill-DELETE { background-color: #f93e3e; }
  span.pill-PATCH { background-color: #50e3c2; }
  span[class^="pill-"]:after {
    content: attr(data-label);
    font-size: 0.9rem;
  }
</style>

[BETA] Operations for KMS External Key Store management.

## <span data-label="POST" class="pill-POST"></span>update-key-store

Update Key Store

```
POST /key-store/{id}/update
```

Updates an External Key Store with a new description, endpoint, or credentials.

### Path parameters

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

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | no | A new detailed description providing additional context about the key store's intended use case.<br/><br/>Max length: `1024`. |
| `proxy` | [New customer-managed XKS proxy settings.](https://community.exoscale.com/reference/api/_schemas/update-key-store-proxy/index.md) | no |  |

<details>
<summary>Example</summary>

```json
{
  "description": "string",
  "proxy": {
    "auth": {
      "key": "string",
      "secret": "string"
    },
    "endpoint": "string"
  }
}
```
</details>


### Responses

**`200`**: Updated the External Key Store

Content-Type: `application/json`


<details>
<summary>Example output</summary>

```json
{}
```
</details>

**`400`**: ### Errors

Not Found: The request was rejected because no key store with the given id exists in the organization.

Bad Request: The request was rejected because of an invalid path parameter.

Conflict: The request was rejected because the key store was concurrently modified. Retry with the latest state.

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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `update-key-store`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.UpdateKeyStore) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.update_key_store) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#updateKeyStore(java.util.UUID,com.exoscale.sdk.model.UpdateKeyStoreRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api update-key-store`

## <span data-label="POST" class="pill-POST"></span>create-key-store

Create Key Store

```
POST /key-store
```

Create an External Key Store after validating the configured customer-managed XKS proxy.

### Request body

Content-Type: `application/json`

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | **yes** | A human-readable display name uniquely identifying the key store within the organization.<br/><br/>Min length: `1`. Max length: `256`. |
| `proxy` | [Key Store Proxy](https://community.exoscale.com/reference/api/_schemas/key-store-proxy/index.md) | **yes** |  |
| `description` | string | no | An optional detailed description providing additional context about the key store's intended use case.<br/><br/>Max length: `1024`. |
| `type` | string | no | The key store type. Only external key stores are supported for this API version.<br/><br/>Allowed values: `external-key-store`.<br/><br/>Default: `external-key-store`. |

<details>
<summary>Example</summary>

```json
{
  "description": "string",
  "name": "string",
  "proxy": {
    "auth": {
      "key": "string",
      "secret": "string"
    },
    "endpoint": "string"
  },
  "type": "external-key-store"
}
```
</details>


### Responses

**`200`**: Created new External Key Store

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `created-at` | string | The creation timestamp.<br/><br/>ISO 8601 date-time. |
| `description` | string | An optional detailed description providing additional context about the key store's intended use case. |
| `id` | string | The globally unique identifier assigned to the key store.<br/><br/>Must be a valid UUID. |
| `name` | string | The display name assigned to the key store. |
| `proxy` | [Key Store Proxy Response](https://community.exoscale.com/reference/api/_schemas/key-store-proxy-response/index.md) |  |
| `status` | string | The current connection status of the key store.<br/><br/>Allowed values: `connected`, `disconnected`. |
| `status-since` | string | The timestamp indicating when the current key store status last transitioned.<br/><br/>ISO 8601 date-time. |
| `type` | string | The key store type.<br/><br/>Allowed values: `external-key-store`. |

<details>
<summary>Example output</summary>

```json
{
  "created-at": "2024-01-01T12:00:00Z",
  "description": "string",
  "id": "string",
  "name": "string",
  "proxy": {
    "auth": {
      "key": "string"
    },
    "endpoint": "string"
  },
  "status": "connected",
  "status-since": "2024-01-01T12:00:00Z",
  "type": "external-key-store"
}
```
</details>

**`400`**: ### Errors

Name Conflict: The request was rejected because a key store with the same name already exists in the organization.

Key Store Proxy Unhealthy: The request was rejected because the customer-managed XKS proxy failed its health check.

Bad Request: The request was rejected because of an invalid request body, path parameter, proxy endpoint, or proxy credentials.

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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `create-key-store`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.CreateKeyStore) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.create_key_store) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#createKeyStore(com.exoscale.sdk.model.CreateKeyStoreRequest))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api create-key-store`

## <span data-label="GET" class="pill-GET"></span>get-key-store

Get Key Store

```
GET /key-store/{id}
```

Fetch an External Key Store including its latest XKS health observation when available.

### Path parameters

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

### Responses

**`200`**: External Key Store

Content-Type: `application/json`


<details>
<summary>Example output</summary>

```json
{}
```
</details>

**`400`**: Bad Request or not 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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `get-key-store`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.GetKeyStore) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.get_key_store) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#getKeyStore(java.util.UUID))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api get-key-store`

## <span data-label="DELETE" class="pill-DELETE"></span>delete-key-store

Delete Key Store

```
DELETE /key-store/{id}
```

Deletes an External Key Store when no KMS keys reference it.

### Path parameters

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

### Responses

**`200`**: Deleted the External Key Store

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `status` | string | Allowed values: `success`, `target-registered`, `already-applied`.<br/><br/>Default: `success`. |

<details>
<summary>Example output</summary>

```json
{
  "status": "success"
}
```
</details>

**`400`**: ### Errors

Not Found: The request was rejected because no key store with the given id exists in the organization.

Key Store Is Referenced: The request was rejected because one or more KMS keys reference the key store.

Bad Request: The request was rejected because of an invalid 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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `delete-key-store`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.DeleteKeyStore) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.delete_key_store) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#deleteKeyStore(java.util.UUID))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api delete-key-store`


---

## Other Operations

## <span data-label="POST" class="pill-POST"></span>connect-key-store

Connect Key Store

```
POST /key-store/{id}/connect
```

Connects an External Key Store after validating the configured customer-managed XKS proxy, and resumes periodic proxy health checks.

### Path parameters

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

### Responses

**`200`**: Connected the External Key Store

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `status` | string | Allowed values: `success`, `target-registered`, `already-applied`.<br/><br/>Default: `success`. |

<details>
<summary>Example output</summary>

```json
{
  "status": "success"
}
```
</details>

**`400`**: ### Errors

Not Found: The request was rejected because no key store with the given id exists in the organization.

Key Store Proxy Unhealthy: The request was rejected because the customer-managed XKS proxy failed its health check.

Bad Request: The request was rejected because of an invalid 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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `connect-key-store`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.ConnectKeyStore) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.connect_key_store) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#connectKeyStore(java.util.UUID))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api connect-key-store`

## <span data-label="POST" class="pill-POST"></span>disconnect-key-store

Disconnect Key Store

```
POST /key-store/{id}/disconnect
```

Disconnects an External Key Store and suspends periodic proxy health checks.

### Path parameters

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

### Responses

**`200`**: Disconnected the External Key Store

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `status` | string | Allowed values: `success`, `target-registered`, `already-applied`.<br/><br/>Default: `success`. |

<details>
<summary>Example output</summary>

```json
{
  "status": "success"
}
```
</details>

**`400`**: ### Errors

Not Found: The request was rejected because no key store with the given id exists in the organization.

Bad Request: The request was rejected because of an invalid 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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `disconnect-key-store`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.DisconnectKeyStore) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.disconnect_key_store) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#disconnectKeyStore(java.util.UUID))

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api disconnect-key-store`

## <span data-label="GET" class="pill-GET"></span>list-key-stores

List Key Stores

```
GET /key-store
```

Lists all key stores configured for an organization.

### Responses

**`200`**: A list of all key stores configured for the organization

Content-Type: `application/json`

| Property | Type | Description |
| --- | --- | --- |
| `key-stores` | array of [List Key Stores Response Entry](https://community.exoscale.com/reference/api/_schemas/list-key-stores-response-entry/index.md) | The key stores configured for the organization. |

<details>
<summary>Example output</summary>

```json
{
  "key-stores": [
    {
      "created-at": "2024-01-01T12:00:00Z",
      "description": "string",
      "id": "string",
      "name": "string",
      "proxy": {
        "auth": {
          "key": "string"
        },
        "endpoint": "string"
      },
      "status": "connected",
      "status-since": "2024-01-01T12:00:00Z",
      "type": "external-key-store"
    }
  ]
}
```
</details>

**`400`**: ### Errors

Bad Request: The request was rejected because of an invalid 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.<br/><br/>Must be a valid URI reference. |

<details>
<summary>Example output</summary>

```json
{
  "detail": "string",
  "status": 0,
  "title": "string",
  "type": "string"
}
```
</details>


SDK reference for `list-key-stores`: [golang](https://pkg.go.dev/github.com/exoscale/egoscale/v3#Client.ListKeyStores) | [Python](https://exoscale.github.io/python-exoscale/v2.html#exoscale.api.v2.Client.list_key_stores) | [Java](https://exoscale.github.io/exoscale-sdk-java/com/exoscale/sdk/api/ExoscaleApi.html#listKeyStores())

[CLI](https://community.exoscale.com/tools/command-line-interface/index.md): `exo api list-key-stores`