/vault/hyok/hostsCreate 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.
| orgId * | query | The organisation's id. |
| 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 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., Example: "luna-prod-01" |
| port * | integer <int32> | TCP port for the KMIP manager endpoint. Example: 5696 |
| protocolVersion * | string | KMIP protocol version to negotiate (floor Example: "1.4" |
| HTTP | K9O Code | Description |
|---|---|---|
| 201 | The host was registered. | |
| 400 | A field isn't valid. | |
| 401 | The request carries no authenticated caller. | |
| 500 | An internal error. Retry later. |
| 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" |
| clusterId | string | null | Cluster identifier; non-null iff 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 Example: "hyokhost_9e8d7c6b-5a49-4f3e-8d2c-1b0a9f8e7d6c" |
| label * | string | Human-readable label (e.g., Example: "luna-prod-01" |
| orgId * | string | Owning org. Example: "org_8kP3wQ9zLm2X" |
| partitionLabel | string | 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 Example: "1.4" |
| status * | "registered" | "in_cluster" | "deregistered" | HYOK host lifecycle status. |
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
{
"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"
}{
"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"
}