Skip to main content
POST/custody-mode-transition

Start Custody Transition

Changes the project's custody mode.

Every data key is re-wrapped under the new mode's KEK, and values are never decrypted to do it. expectedFromMode must match the project's current mode, so two changes can't cross.

The call returns when the transition is complete.

Needs PROJECT_ADMIN.

Parameters
projectId *query

The project's id.

regionquery

The residency region the call is made in.

Request body
attestationReportany
One of: null
or: object
measurementstring | null

The TEE-emitted measurement, base64.

Advisory: the gate uses the measurement from the verified quote, and records this echo.

Example: "q83vEjRWeJCrze8SNFZ4kKvN7xI0VniQq83vEjRWeJA="
quote *string

The signed TEE evidence, base64: a TDX DCAP quote or a 1184-byte SEV-SNP report.

Example: "AgAAAAIAAAAfAAMAAAAAAAEAAAAAAAAAAAAAAAAAAAA="
teePlatform *"intel-tdx" | "amd-sev-snp" | "intel-sgx" | "aws-nitro-enclave"

The TEE platform of an attestation report.

voluntaryboolean | null

true when the workload re-attests on its own, not because kibo asked.

Example: false
byokConfigany
One of: null
or: any
One of: object
audiencestring | null

The aud of the KMS-federation token; omit for the platform default.

Example: "sts.amazonaws.com"
iamRoleArn *string

The customer's role kibo assumes; its trust names GET /vault/custody-trust.

Example: "arn:aws:iam::111122223333:role/kibo-byok"
keyArn *string

The KMS key ARN.

Example: "arn:aws:kms:eu-central-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"
provider *"aws-kms"
region *string

The AWS region of the key.

Example: "eu-central-1"
or: object
audiencestring | null

The aud of the KMS-federation token; omit for the provider's resource name.

Example: "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo"
keyName *string

projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>.

Example: "projects/acme-prod/locations/europe-west3/keyRings/kibo/cryptoKeys/byok"
provider *"gcp-cloud-kms"
workloadIdentityProvider *string

The workload identity provider that trusts kibo's tenant issuer.

Example: "projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo"
or: object
audiencestring | null

The aud of the KMS-federation token; omit for api://AzureADTokenExchange.

Example: "api://AzureADTokenExchange"
clientId *string

The Entra app (client) id holding the federated credential.

Example: "0f1e2d3c-4b5a-6978-8091-a2b3c4d5e6f7"
keyIdentifier *string

The key identifier, https://<vault>.vault.azure.net/keys/<name>.

Example: "https://acme-prod.vault.azure.net/keys/kibo-byok"
provider *"azure-key-vault"
region *string

The Azure region of the vault.

Example: "westeurope"
tenantId *string

The customer's Entra tenant id.

Example: "72f988bf-86f1-41af-91ab-2d7cd011db47"
or: object
audiencestring | null

The aud of the KMS-federation token, for JWT auth.

Example: "vault"
auth *any

OpenAPI shape of HashiCorp Vault auth (documentation; kibo_byok::VaultAuth, tagged by method).

Launch accepts token only; approle and jwt are refused with a 400 (BYOK_PROVIDER_NOT_SUPPORTED).

One of: object
method *"token"
token *string

The Vault token.

Write-only: never returned.

Example: "hvs.CAESIJ4xXXXXXXXXXXXXXXXXXXXX"
or: object
method *"approle"
roleId *string

The AppRole role id.

Example: "db02de05-fa39-4855-059b-67221c5c2f63"
secretId *string

The AppRole secret id.

Write-only: never returned.

Example: "6a174c20-f6de-a53c-74d2-6018fcceff64"
or: object
jwt *string

The JWT.

Write-only: never returned.

Example: "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJraWJvIn0.c2ln"
method *"jwt"
role *string

The JWT auth role.

Example: "kibo"
keyName *string

The Transit key name.

Example: "kibo-byok"
namespacestring | null

The Vault Enterprise namespace; omit for the root namespace.

Example: "acme/prod"
provider *"hashicorp-vault"
transitMountPath *string

The Transit secrets engine mount path.

Example: "transit"
vaultUrl *string

The Vault server URL.

Example: "https://vault.acme.example:8200"
expectedFromMode *"PLATFORM_MANAGED" | "CONFIDENTIAL_WORKLOAD" | "BYOK" | "HYOK"

Custody mode of a project's vault.

hyokConfigany
One of: null
or: any
One of: object
clusterId *string

hyokcluster_*: the org cluster to attach into.

Example: "hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"
keyUid *string

The KMIP Unique Identifier of the customer's key on their manager.

Example: "e3c5a2b1-7d4f-4a9e-b6c8-1f2e3d4c5b6a"
provider *"kmip"
or: object
audiencestring | null

The aud of the KMS-federation token; omit for the platform default.

Example: "sts.amazonaws.com"
customKeyStoreArn *string

The custom key store ARN; its region must match the key's.

Example: "arn:aws:kms:eu-central-1:111122223333:custom-key-store/cks-1234567890abcdef0"
iamRoleArn *string

The customer's role kibo assumes with the project's ExternalId.

Example: "arn:aws:iam::111122223333:role/kibo-hyok"
keyArn *string

The KMS key ARN.

Example: "arn:aws:kms:eu-central-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"
provider *"aws-kms-custom-key-store"
region *string

The AWS region of the key and the store.

Example: "eu-central-1"
or: object
audiencestring | null

The aud of the KMS-federation token; omit for the provider's resource name.

Example: "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo"
keyName *string

projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>.

Example: "projects/acme-prod/locations/europe-west3/keyRings/kibo/cryptoKeys/hyok"
provider *"gcp-cloud-kms-hsm"
workloadIdentityProvider *string

The workload identity provider that trusts kibo's tenant issuer.

Example: "projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo"
or: object
audiencestring | null

The aud of the KMS-federation token; omit for api://AzureADTokenExchange.

Example: "api://AzureADTokenExchange"
clientId *string

The Entra app (client) id holding the federated credential.

Example: "0f1e2d3c-4b5a-6978-8091-a2b3c4d5e6f7"
hsmPoolUri *string

The pool URI, https://<pool>.managedhsm.azure.net.

Example: "https://acme-prod.managedhsm.azure.net"
keyName *string

The key's name in the pool.

Example: "kibo-hyok"
provider *"azure-managed-hsm"
region *string

The Azure region of the pool.

Example: "westeurope"
tenantId *string

The customer's Entra tenant id.

Example: "72f988bf-86f1-41af-91ab-2d7cd011db47"
regionsobject[] | null

Option B: exactly the project's active regions, each once, each with its config.

toMode *"PLATFORM_MANAGED" | "CONFIDENTIAL_WORKLOAD" | "BYOK" | "HYOK"

Custody mode of a project's vault.

Responses
HTTPK9O CodeDescription
200The completed transition job, or for `CONFIDENTIAL_WORKLOAD`, the attestation.
400The body isn't valid: a missing config, a repeated region, or a transition that isn't allowed.
403The caller isn't a `PROJECT_ADMIN` of the project.
409`K9O_CUSTODY_MODE_CHANGED`: `expectedFromMode` doesn't match. `K9O_CUSTODY_TRANSITION_IN_PROGRESS`: a change is already running. `K9O_CUSTODY_TRANSITION_REGION_SET_MISMATCH`: the regions don't match the project's, and `context` lists the missing and extra ones.
502`K9O_UPSTREAM_UNAVAILABLE`: a dependency didn't answer. Retry later.
503The customer key or the KEK couldn't be reached.
Response body (200)
completedAtstring <date-time> | null

Transition completion timestamp; null while in progress.

The database time of the completing transaction, identical on the POST answer, the poll and GET /vault.

Example: "2026-11-15T09:30:00.123Z"
completedSeqinteger <int64> | null

The project's completed jobs in strictly increasing order.

Compare jobs on this, never on completedAt or jobId.

Absent until the job completes.

Example: 12
errorany
One of: null
or: object
code *string

Machine-readable error code.

Example: "BYOK_KEY_UNREACHABLE"
message *string

Human-readable error message.

Example: "The customer KMS key could not be reached."
fromMode *"PLATFORM_MANAGED" | "CONFIDENTIAL_WORKLOAD" | "BYOK" | "HYOK"

Custody mode of a project's vault.

jobId *string

Job identifier — UUID prefixed "ctjob_".

Example: "ctjob_7c9e6679-7425-40de-944b-e07fc1f90ae7"
projectId *string

Project this transition is for.

Example: "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"
rekeyProgress *number <double>

Re-key progress (0.0 .. 1.0); meaningful only when rekey_required == true.

Example: 1
rekeyRequired *boolean

Whether a re-key is required for this transition.

Example: true
restoreEpochstring | null

The id of the last restore this kibo came back from, or null if it was never restored.

When it changes, completedSeq numbering started again.

Example: "rfn_3Hk8Pz2Qw7Ln"
restoreGenerationinteger <int64> | null

The ordered restoreGeneration of that episode (the HWM its lift published to the external witness); a gateway accepts a watermark reset only for a GREATER one.

Example: 2
startedAt *string <date-time>

Transition start timestamp.

Example: "2026-11-01T08:00:00.000Z"
status *"in_progress" | "complete" | "failed"

Custody-mode-transition job lifecycle status.

toMode *"PLATFORM_MANAGED" | "CONFIDENTIAL_WORKLOAD" | "BYOK" | "HYOK"

Custody mode of a project's vault.

cURL
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/custody-mode-transition' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "toMode": "BYOK",
  "expectedFromMode": "PLATFORM_MANAGED",
  "byokConfig": {
    "provider": "aws-kms",
    "keyArn": "arn:aws:kms:eu-central-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "iamRoleArn": "arn:aws:iam::111122223333:role/kibo-byok",
    "region": "eu-central-1"
  }
}'

Showing example in cURL

Request example
{
  "toMode": "BYOK",
  "expectedFromMode": "PLATFORM_MANAGED",
  "byokConfig": {
    "provider": "aws-kms",
    "keyArn": "arn:aws:kms:eu-central-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab",
    "iamRoleArn": "arn:aws:iam::111122223333:role/kibo-byok",
    "region": "eu-central-1"
  }
}
Response example (200)
{
  "completedAt": "2026-11-15T09:30:00.123Z",
  "completedSeq": 12,
  "fromMode": "PLATFORM_MANAGED",
  "jobId": "ctjob_7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "projectId": "3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b",
  "rekeyProgress": 1,
  "rekeyRequired": true,
  "restoreEpoch": "rfn_3Hk8Pz2Qw7Ln",
  "restoreGeneration": 2,
  "startedAt": "2026-11-01T08:00:00.000Z",
  "status": "in_progress",
  "toMode": "PLATFORM_MANAGED"
}

More in Custody & Exit