# Start Custody Transition

`POST /custody-mode-transition` · Keys & Secrets · Custody & Exit

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

| Name | In | Required | Description |
|---|---|---|---|
| `projectId` | query | yes | The project's id. Example: `"3f2c9a4e-8b1d-4c6f-9e2a-7d5b1c0a4e8f"`. |
| `region` | query | no | The residency region the call is made in. Example: `"de01"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `attestationReport` | object | no |  |
| _one of_ | | |  |
| _or_ | | |  |
| `attestationReport.measurement` | string \| null | no | The TEE-emitted measurement, base64. Advisory: the gate uses the measurement from the verified quote, and records this echo. Example: `"q83vEjRWeJCrze8SNFZ4kKvN7xI0VniQq83vEjRWeJA="`. |
| `attestationReport.quote` | string | yes | The signed TEE evidence, base64: a TDX DCAP quote or a 1184-byte SEV-SNP report. Example: `"AgAAAAIAAAAfAAMAAAAAAAEAAAAAAAAAAAAAAAAAAAA="`. |
| `attestationReport.teePlatform` | enum ("intel-tdx", "amd-sev-snp", "intel-sgx", "aws-nitro-enclave") | yes | The TEE platform of an attestation report. |
| `attestationReport.voluntary` | boolean \| null | no | `true` when the workload re-attests on its own, not because kibo asked. Example: `false`. |
| `byokConfig` | object | no |  |
| _one of_ | | |  |
| _or_ | | |  |
| _one of_ | | |  |
| `byokConfig.audience` | string \| null | no | The `aud` of the KMS-federation token; omit for the platform default. Example: `"sts.amazonaws.com"`. |
| `byokConfig.iamRoleArn` | string | yes | The customer's role kibo assumes; its trust names `GET /vault/custody-trust`. Example: `"arn:aws:iam::111122223333:role/kibo-byok"`. |
| `byokConfig.keyArn` | string | yes | The KMS key ARN. Example: `"arn:aws:kms:eu-central-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab"`. |
| `byokConfig.provider` | enum ("aws-kms") | yes |  |
| `byokConfig.region` | string | yes | The AWS region of the key. Example: `"eu-central-1"`. |
| _or_ | | |  |
| `byokConfig.audience` | string \| null | no | 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"`. |
| `byokConfig.keyName` | string | yes | `projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>`. Example: `"projects/acme-prod/locations/europe-west3/keyRings/kibo/cryptoKeys/byok"`. |
| `byokConfig.provider` | enum ("gcp-cloud-kms") | yes |  |
| `byokConfig.workloadIdentityProvider` | string | yes | The workload identity provider that trusts kibo's tenant issuer. Example: `"projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo"`. |
| _or_ | | |  |
| `byokConfig.audience` | string \| null | no | The `aud` of the KMS-federation token; omit for `api://AzureADTokenExchange`. Example: `"api://AzureADTokenExchange"`. |
| `byokConfig.clientId` | string | yes | The Entra app (client) id holding the federated credential. Example: `"0f1e2d3c-4b5a-6978-8091-a2b3c4d5e6f7"`. |
| `byokConfig.keyIdentifier` | string | yes | The key identifier, `https://<vault>.vault.azure.net/keys/<name>`. Example: `"https://acme-prod.vault.azure.net/keys/kibo-byok"`. |
| `byokConfig.provider` | enum ("azure-key-vault") | yes |  |
| `byokConfig.region` | string | yes | The Azure region of the vault. Example: `"westeurope"`. |
| `byokConfig.tenantId` | string | yes | The customer's Entra tenant id. Example: `"72f988bf-86f1-41af-91ab-2d7cd011db47"`. |
| _or_ | | |  |
| `byokConfig.audience` | string \| null | no | The `aud` of the KMS-federation token, for JWT auth. Example: `"vault"`. |
| `byokConfig.auth` | object | yes | 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_ | | |  |
| `byokConfig.auth.method` | enum ("token") | yes |  |
| `byokConfig.auth.token` | string | yes | The Vault token. Write-only: never returned. Example: `"hvs.CAESIJ4xXXXXXXXXXXXXXXXXXXXX"`. |
| _or_ | | |  |
| `byokConfig.auth.method` | enum ("approle") | yes |  |
| `byokConfig.auth.roleId` | string | yes | The AppRole role id. Example: `"db02de05-fa39-4855-059b-67221c5c2f63"`. |
| `byokConfig.auth.secretId` | string | yes | The AppRole secret id. Write-only: never returned. Example: `"6a174c20-f6de-a53c-74d2-6018fcceff64"`. |
| _or_ | | |  |
| `byokConfig.auth.jwt` | string | yes | The JWT. Write-only: never returned. Example: `"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEifQ.eyJzdWIiOiJraWJvIn0.c2ln"`. |
| `byokConfig.auth.method` | enum ("jwt") | yes |  |
| `byokConfig.auth.role` | string | yes | The JWT auth role. Example: `"kibo"`. |
| `byokConfig.keyName` | string | yes | The Transit key name. Example: `"kibo-byok"`. |
| `byokConfig.namespace` | string \| null | no | The Vault Enterprise namespace; omit for the root namespace. Example: `"acme/prod"`. |
| `byokConfig.provider` | enum ("hashicorp-vault") | yes |  |
| `byokConfig.transitMountPath` | string | yes | The Transit secrets engine mount path. Example: `"transit"`. |
| `byokConfig.vaultUrl` | string | yes | The Vault server URL. Example: `"https://vault.acme.example:8200"`. |
| `expectedFromMode` | enum ("PLATFORM_MANAGED", "CONFIDENTIAL_WORKLOAD", "BYOK", "HYOK") | yes | Custody mode of a project's vault. |
| `hyokConfig` | object | no |  |
| _one of_ | | |  |
| _or_ | | |  |
| _one of_ | | |  |
| `hyokConfig.clusterId` | string | yes | `hyokcluster_*`: the org cluster to attach into. Example: `"hyokcluster_0b6f2c1e-3d4a-4b5c-8d9e-0f1a2b3c4d5e"`. |
| `hyokConfig.keyUid` | string | yes | The KMIP Unique Identifier of the customer's key on their manager. Example: `"e3c5a2b1-7d4f-4a9e-b6c8-1f2e3d4c5b6a"`. |
| `hyokConfig.provider` | enum ("kmip") | yes |  |
| _or_ | | |  |
| `hyokConfig.audience` | string \| null | no | The `aud` of the KMS-federation token; omit for the platform default. Example: `"sts.amazonaws.com"`. |
| `hyokConfig.customKeyStoreArn` | string | yes | 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"`. |
| `hyokConfig.iamRoleArn` | string | yes | The customer's role kibo assumes with the project's `ExternalId`. Example: `"arn:aws:iam::111122223333:role/kibo-hyok"`. |
| `hyokConfig.keyArn` | string | yes | The KMS key ARN. Example: `"arn:aws:kms:eu-central-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab"`. |
| `hyokConfig.provider` | enum ("aws-kms-custom-key-store") | yes |  |
| `hyokConfig.region` | string | yes | The AWS region of the key and the store. Example: `"eu-central-1"`. |
| _or_ | | |  |
| `hyokConfig.audience` | string \| null | no | 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"`. |
| `hyokConfig.keyName` | string | yes | `projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k>`. Example: `"projects/acme-prod/locations/europe-west3/keyRings/kibo/cryptoKeys/hyok"`. |
| `hyokConfig.provider` | enum ("gcp-cloud-kms-hsm") | yes |  |
| `hyokConfig.workloadIdentityProvider` | string | yes | The workload identity provider that trusts kibo's tenant issuer. Example: `"projects/123456789/locations/global/workloadIdentityPools/kibo/providers/kibo"`. |
| _or_ | | |  |
| `hyokConfig.audience` | string \| null | no | The `aud` of the KMS-federation token; omit for `api://AzureADTokenExchange`. Example: `"api://AzureADTokenExchange"`. |
| `hyokConfig.clientId` | string | yes | The Entra app (client) id holding the federated credential. Example: `"0f1e2d3c-4b5a-6978-8091-a2b3c4d5e6f7"`. |
| `hyokConfig.hsmPoolUri` | string | yes | The pool URI, `https://<pool>.managedhsm.azure.net`. Example: `"https://acme-prod.managedhsm.azure.net"`. |
| `hyokConfig.keyName` | string | yes | The key's name in the pool. Example: `"kibo-hyok"`. |
| `hyokConfig.provider` | enum ("azure-managed-hsm") | yes |  |
| `hyokConfig.region` | string | yes | The Azure region of the pool. Example: `"westeurope"`. |
| `hyokConfig.tenantId` | string | yes | The customer's Entra tenant id. Example: `"72f988bf-86f1-41af-91ab-2d7cd011db47"`. |
| `regions` | array of object \| null | no | Option B: exactly the project's active regions, each once, each with its config. |
| `toMode` | enum ("PLATFORM_MANAGED", "CONFIDENTIAL_WORKLOAD", "BYOK", "HYOK") | yes | Custody mode of a project's vault. |

```json
{
  "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"
  }
}
```

## Responses

- **200**: The completed transition job, or for `CONFIDENTIAL_WORKLOAD`, the attestation.

| Field | Type | Required | Description |
|---|---|---|---|
| `completedAt` | string (date-time) \| null | no | 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"`. |
| `completedSeq` | integer (int64) \| null | no | 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`. |
| `error` | object | no |  |
| _one of_ | | |  |
| _or_ | | |  |
| `error.code` | string | yes | Machine-readable error code. Example: `"BYOK_KEY_UNREACHABLE"`. |
| `error.message` | string | yes | Human-readable error message. Example: `"The customer KMS key could not be reached."`. |
| `fromMode` | enum ("PLATFORM_MANAGED", "CONFIDENTIAL_WORKLOAD", "BYOK", "HYOK") | yes | Custody mode of a project's vault. |
| `jobId` | string | yes | Job identifier — UUID prefixed `"ctjob_"`. Example: `"ctjob_7c9e6679-7425-40de-944b-e07fc1f90ae7"`. |
| `projectId` | string | yes | Project this transition is for. Example: `"3f2b8c1e-5d4a-4e6f-9a7b-1c2d3e4f5a6b"`. |
| `rekeyProgress` | number (double) | yes | Re-key progress (0.0 .. 1.0); meaningful only when `rekey_required == true`. Example: `1`. |
| `rekeyRequired` | boolean | yes | Whether a re-key is required for this transition. Example: `true`. |
| `restoreEpoch` | string \| null | no | 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"`. |
| `restoreGeneration` | integer (int64) \| null | no | 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) | yes | Transition start timestamp. Example: `"2026-11-01T08:00:00.000Z"`. |
| `status` | enum ("in_progress", "complete", "failed") | yes | Custody-mode-transition job lifecycle status. |
| `toMode` | enum ("PLATFORM_MANAGED", "CONFIDENTIAL_WORKLOAD", "BYOK", "HYOK") | yes | Custody mode of a project's vault. |


## Errors

| HTTP | Description |
|---|---|
| 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. |

## Code samples

### cURL

```bash
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"
  }
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/custody-mode-transition', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "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"
  }
}),
});
const { data, meta } = await res.json();
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/keys-secrets/start-custody-transition
