Skip to main content
PATCH/vault/hyok/hosts/{host_id}

Update Host

Changes a host's label, endpoint or certificate references.

The customer key is unchanged, so no data key is re-wrapped.

A new hostname or certificate applies from the next connection, and the server certificate must still match the hostname.

Needs ORG_ADMIN.

Parameters
orgId *query

The organisation's id.

host_id *path

The host's id: hyokhost_ and a UUID.

Request body
caRefstring | null

Rotated secret-store handle for the customer's server trust-anchor CA.

Example: "secret://hyok/kmip-server-ca-2026"
clientCertRefstring | null

Rotated secret-store handle for the platform mTLS client identity.

Example: "secret://hyok/kmip-client-identity-2026"
hostnamestring | null

New KMIP manager hostname (must match the server-cert SAN).

Example: "kmip2.acme.example"
labelstring | null

New human-readable label.

Example: "luna-prod-02"
portinteger <int32> | null

New KMIP manager port.

Example: 5696
protocolVersionstring | null

New KMIP protocol version (floor 1.4).

Example: "2.0"
Responses
HTTPK9O CodeDescription
200The updated host.
400A field or the port isn't valid.
404No such host.
500An internal error. Retry later.
Response body (200)
caRef *string

Secret-store handle for the customer's server trust-anchor CA.

Example: "secret://hyok/kmip-server-ca"
clientCertRef *string

Secret-store handle for the platform mTLS client identity.

Example: "secret://hyok/kmip-client-identity"
clusterIdstring | null

Cluster identifier; non-null iff status == in_cluster.

Example: "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"
createdAt *string <date-time>

Host registration timestamp.

Example: "2026-11-01T08:00:00.000Z"
hostname *string

KMIP manager hostname (matches the server-cert SAN).

Example: "kmip.acme.example"
hsmModel *"thales-luna" | "entrust-nshield" | "aws-cloudhsm"

HSM model variants supported in the HYOK host registry.

id *string

Host identifier — UUID prefixed "hyokhost_".

Example: "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c"
label *string

Human-readable label (e.g., "luna-prod-01").

Example: "luna-prod-01"
orgId *string

Owning org.

Example: "org_8kP3wQ9zLm2X"
partitionLabelstring | null

PKCS#11-era partition label — retired for the KMIP single-host shape; present only on legacy rows.

Example: "partition-1"
port *integer <int32>

KMIP manager port.

Example: 5696
protocolVersion *string

KMIP protocol version negotiated (floor 1.4).

Example: "1.4"
status *"registered" | "in_cluster" | "deregistered"

HYOK host lifecycle status.

cURL
curl -X PATCH 'https://<org>.api-<region>.k9o.io/@storefront/vault/hyok/hosts/<hostId>' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "clientCertRef": "secret://hyok/kmip-client-identity-2026",
  "caRef": "secret://hyok/kmip-server-ca-2026"
}'

Showing example in cURL

Request example
{
  "clientCertRef": "secret://hyok/kmip-client-identity-2026",
  "caRef": "secret://hyok/kmip-server-ca-2026"
}
Response example (200)
{
  "caRef": "secret://hyok/kmip-server-ca",
  "clientCertRef": "secret://hyok/kmip-client-identity",
  "clusterId": "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e",
  "createdAt": "2026-11-01T08:00:00.000Z",
  "hostname": "kmip.acme.example",
  "hsmModel": "thales-luna",
  "id": "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c",
  "label": "luna-prod-01",
  "orgId": "org_8kP3wQ9zLm2X",
  "partitionLabel": "partition-1",
  "port": 5696,
  "protocolVersion": "1.4",
  "status": "registered"
}

More in HYOK Clusters & Hosts