/custody-mode-transitionStart 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.
| projectId * | query | The project's id. |
| region | query | The residency region the call is made in. |
| attestationReport | any | |
| One of: null | ||
| or: object | ||
| measurement | string | 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. |
| voluntary | boolean | null |
Example: false |
| byokConfig | any | |
| One of: null | ||
| or: any | ||
| One of: object | ||
| audience | string | null | The Example: "sts.amazonaws.com" |
| iamRoleArn * | string | The customer's role kibo assumes; its trust names 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 | ||
| audience | string | null | The Example: "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo" |
| keyName * | string |
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 | ||
| audience | string | null | The 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, 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 | ||
| audience | string | null | The Example: "vault" |
| auth * | any | OpenAPI shape of HashiCorp Vault auth (documentation; Launch accepts |
| 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" |
| namespace | string | 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. |
| hyokConfig | any | |
| One of: null | ||
| or: any | ||
| One of: object | ||
| clusterId * | string |
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 | ||
| audience | string | null | The 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 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 | ||
| audience | string | null | The Example: "//iam.googleapis.com/projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo" |
| keyName * | string |
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 | ||
| audience | string | null | The 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, 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" |
| regions | object[] | 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. |
| HTTP | K9O Code | Description |
|---|---|---|
| 200 | The completed transition job, or for `CONFIDENTIAL_WORKLOAD`, the attestation. | |
| 400 | The body isn't valid: a missing config, a repeated region, or a transition that isn't allowed. | |
| 403 | The 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. | |
| 503 | The customer key or the KEK couldn't be reached. |
| completedAt | string <date-time> | null | Transition completion timestamp; The database time of the completing transaction, identical on the POST answer, the poll and Example: "2026-11-15T09:30:00.123Z" |
| completedSeq | integer <int64> | null | The project's completed jobs in strictly increasing order. Compare jobs on this, never on Absent until the job completes. Example: 12 |
| error | any | |
| 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 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 Example: 1 |
| rekeyRequired * | boolean | Whether a re-key is required for this transition. Example: true |
| restoreEpoch | string | null | The id of the last restore this kibo came back from, or null if it was never restored. When it changes, Example: "rfn_3Hk8Pz2Qw7Ln" |
| restoreGeneration | integer <int64> | null | The ordered 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 -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
{
"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"
}
}{
"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"
}