Skip to main content
POST/vault/hyok/hosts

Create Host

Registers a KMIP endpoint and the certificate references kibo uses to reach it.

A new host is registered until a cluster includes it.

Needs ORG_ADMIN.

Parameters
orgId *query

The organisation's id.

Request body
caRef *string

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

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

A reference to the client certificate and key kibo presents to the KMIP server, never the PEM itself.

Example: "secret://hyok/kmip-client-identity"
hostname *string

Network hostname / DNS for the KMIP manager endpoint.

MUST match the manager server-cert subjectAltName (rustls verifies SAN).

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

HSM model variants supported in the HYOK host registry.

label *string

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

Example: "luna-prod-01"
port *integer <int32>

TCP port for the KMIP manager endpoint.

Example: 5696
protocolVersion *string

KMIP protocol version to negotiate (floor 1.4).

Example: "1.4"
Responses
HTTPK9O CodeDescription
201The host was registered.
400A field isn't valid.
401The request carries no authenticated caller.
500An internal error. Retry later.
Response body (201)
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 POST 'https://<org>.api-<region>.k9o.io/@storefront/vault/hyok/hosts' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "label": "luna-prod-01",
  "hsmModel": "thales-luna",
  "hostname": "kmip.acme.example",
  "port": 5696,
  "protocolVersion": "1.4",
  "clientCertRef": "secret://hyok/kmip-client-identity",
  "caRef": "secret://hyok/kmip-server-ca"
}'

Showing example in cURL

Request example
{
  "label": "luna-prod-01",
  "hsmModel": "thales-luna",
  "hostname": "kmip.acme.example",
  "port": 5696,
  "protocolVersion": "1.4",
  "clientCertRef": "secret://hyok/kmip-client-identity",
  "caRef": "secret://hyok/kmip-server-ca"
}
Response example (201)
{
  "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