Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

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

idstringRequired

Unique ID of the vault key.

namestringRequired

The key's name, such as Storefront runtime.

productIdsarray of stringsRequired

IDs of the products whose secrets the key can pull.

environmentIdsarray of stringsRequired

IDs of the production environments the key can pull from.

createdAtstringRequired

When the key was created, as an ISO 8601 timestamp.

The VaultKey object
{  "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.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Returns

Returns an array of VaultKey objects. Status 200.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
GET/v1/workspaces/{slug}/vault/keys
curl https://api.qa.clankership.net/v1/workspaces/acme/vault/keys \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
[  {    "id": "Vk8MtR3pLx6N",    "name": "Storefront runtime",    "productIds": [      "Pr4GtY9sLm3B"    ],    "environmentIds": [      "En1MwX6cTb7F"    ],    "createdAt": "2026-10-01T16:20:00.000Z"  }]

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.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Body parameters

namestringRequired

A name for the key, 1 to 100 characters, such as Storefront runtime.

productIdsarray of stringsRequired

IDs of active products in the workspace whose secrets the key may pull. At least one.

environmentIdsarray of stringsRequired

IDs of active production environments the key may pull from. At least one.

Returns

Returns an object with these fields. Status 200.

A new vault key with its value, which is never shown again.

idstringRequired

Unique ID of the vault key.

namestringRequired

The key's name.

productIdsarray of stringsRequired

IDs of the products whose secrets the key can pull.

environmentIdsarray of stringsRequired

IDs of the production environments the key can pull from.

secretstringRequired

The key, starting with ctvk_. It is shown only in this response.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
POST/v1/workspaces/{slug}/vault/keys
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/vault/keys \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Storefront runtime",    "productIds": [      "Pr4GtY9sLm3B"    ],    "environmentIds": [      "En1MwX6cTb7F"    ]  }'
Response200
{  "id": "Vk8MtR3pLx6N",  "name": "Storefront runtime",  "productIds": [    "Pr4GtY9sLm3B"  ],  "environmentIds": [    "En1MwX6cTb7F"  ],  "secret": "ctvk_7HqP2mXv9LsR4tWc8NbK3dFj6YgZ1aQe"}

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.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

idstringRequired

The vault key's ID, such as Vk8MtR3pLx6N.

Body parameters

namestringRequired

A name for the key, 1 to 100 characters, such as Storefront runtime.

productIdsarray of stringsRequired

IDs of active products in the workspace whose secrets the key may pull. At least one.

environmentIdsarray of stringsRequired

IDs of active production environments the key may pull from. At least one.

Returns

Returns an object with these fields. Status 200.

The key's new name and scope.

idstringRequired

Unique ID of the vault key.

namestringRequired

The key's name.

productIdsarray of stringsRequired

IDs of the products whose secrets the key can pull.

environmentIdsarray of stringsRequired

IDs of the production environments the key can pull from.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
PATCH/v1/workspaces/{slug}/vault/keys/{id}
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/vault/keys/{id} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "name": "Storefront runtime",    "productIds": [      "Pr4GtY9sLm3B"    ],    "environmentIds": [      "En1MwX6cTb7F"    ]  }'
Response200
{  "id": "Vk8MtR3pLx6N",  "name": "Storefront runtime",  "productIds": [    "Pr4GtY9sLm3B"  ],  "environmentIds": [    "En1MwX6cTb7F"  ]}

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.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

idstringRequired

The vault key's ID, such as Vk8MtR3pLx6N.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the change was made.

Always true

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
POST/v1/workspaces/{slug}/vault/keys/{id}/revoke
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/vault/keys/{id}/revoke \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "ok": true}
NextHealth