# Vault keys

A vault key (`ctvk_…`) lets a running deployment pull its production secrets. Each key names the products and production environments it may pull, and it cannot pull non-production values. Admins and owners create, change and revoke vault keys.

## The VaultKey object

A key that pulls production secrets for the products and environments it names.

### Attributes

- `id` (string, required): Unique ID of the vault key.
- `name` (string, required): The key's name, such as Storefront runtime.
- `productIds` (array of strings, required): IDs of the products whose secrets the key can pull.
- `environmentIds` (array of strings, required): IDs of the production environments the key can pull from.
- `createdAt` (string, required): When the key was created, as an ISO 8601 timestamp.

### Example

```json
{
  "id": "Vk8MtR3pLx6N",
  "name": "Storefront runtime",
  "productIds": [
    "Pr4GtY9sLm3B"
  ],
  "environmentIds": [
    "En1MwX6cTb7F"
  ],
  "createdAt": "2026-10-01T16:20:00.000Z"
}
```

## List vault keys

`GET /v1/workspaces/{slug}/vault/keys`

Returns the workspace's vault keys without their values. Revoked keys are left out.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.

### Returns

Returns an array of [VaultKey](https://docs.qa.clankership.net/api/vault-keys/object.md) objects. The status is 200.

### Request

```bash
curl https://api.qa.clankership.net/v1/workspaces/{slug}/vault/keys \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
[
  {
    "id": "Vk8MtR3pLx6N",
    "name": "Storefront runtime",
    "productIds": [
      "Pr4GtY9sLm3B"
    ],
    "environmentIds": [
      "En1MwX6cTb7F"
    ],
    "createdAt": "2026-10-01T16:20:00.000Z"
  }
]
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Create a vault key

`POST /v1/workspaces/{slug}/vault/keys`

Creates a key that can pull production secrets for the chosen products and production environments. The response holds the key's value, which is never shown again. Only admins and owners can create vault keys.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `name` (string, required): A name for the key, 1 to 100 characters, such as Storefront runtime.
- `productIds` (array of strings, required): IDs of active products in the workspace whose secrets the key may pull. At least one.
- `environmentIds` (array of strings, required): IDs of active production environments the key may pull from. At least one.

### Returns

Returns an object with these fields. The status is 200. A new vault key with its value, which is never shown again.

- `id` (string, required): Unique ID of the vault key.
- `name` (string, required): The key's name.
- `productIds` (array of strings, required): IDs of the products whose secrets the key can pull.
- `environmentIds` (array of strings, required): IDs of the production environments the key can pull from.
- `secret` (string, required): The key, starting with ctvk_. It is shown only in this response.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/vault/keys \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Storefront runtime",
    "productIds": [
      "Pr4GtY9sLm3B"
    ],
    "environmentIds": [
      "En1MwX6cTb7F"
    ]
  }'
```

### Response

```json
{
  "id": "Vk8MtR3pLx6N",
  "name": "Storefront runtime",
  "productIds": [
    "Pr4GtY9sLm3B"
  ],
  "environmentIds": [
    "En1MwX6cTb7F"
  ],
  "secret": "ctvk_7HqP2mXv9LsR4tWc8NbK3dFj6YgZ1aQe"
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Update a vault key

`PATCH /v1/workspaces/{slug}/vault/keys/{id}`

Replaces the key's name and scope; its value stays the same. Only admins and owners can update vault keys, and a revoked key fails with NotFound.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `id` (string, in path, required): The vault key's ID, such as Vk8MtR3pLx6N.
- `name` (string, required): A name for the key, 1 to 100 characters, such as Storefront runtime.
- `productIds` (array of strings, required): IDs of active products in the workspace whose secrets the key may pull. At least one.
- `environmentIds` (array of strings, required): IDs of active production environments the key may pull from. At least one.

### Returns

Returns an object with these fields. The status is 200. The key's new name and scope.

- `id` (string, required): Unique ID of the vault key.
- `name` (string, required): The key's name.
- `productIds` (array of strings, required): IDs of the products whose secrets the key can pull.
- `environmentIds` (array of strings, required): IDs of the production environments the key can pull from.

### Request

```bash
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/{slug}/vault/keys/{id} \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Storefront runtime",
    "productIds": [
      "Pr4GtY9sLm3B"
    ],
    "environmentIds": [
      "En1MwX6cTb7F"
    ]
  }'
```

### Response

```json
{
  "id": "Vk8MtR3pLx6N",
  "name": "Storefront runtime",
  "productIds": [
    "Pr4GtY9sLm3B"
  ],
  "environmentIds": [
    "En1MwX6cTb7F"
  ]
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.

## Revoke a vault key

`POST /v1/workspaces/{slug}/vault/keys/{id}/revoke`

Revokes the key, so its next pull fails with Unauthorized. Only admins and owners can revoke vault keys.

### Parameters

- `slug` (string, in path, required): The workspace's slug or ID, such as acme.
- `id` (string, in path, required): The vault key's ID, such as Vk8MtR3pLx6N.

### Returns

Returns an object with these fields. The status is 200.

- `ok` (boolean, required): Always true: the change was made. Always `true`.

### Request

```bash
curl -X POST https://api.qa.clankership.net/v1/workspaces/{slug}/vault/keys/{id}/revoke \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

### Response

```json
{
  "ok": true
}
```

### Errors

- `400` `InvalidInput`: The request is malformed, or a value is not allowed.
- `401` `Unauthorized`: The request has no valid API key.
- `403` `Forbidden`: The key's user or role may not do this.
- `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it.
- `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use.
- `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.