# Rewrap

`POST /crypto/rewrap` · Core · Encryption

Re-seals up to 100 ciphertexts under the project's current key in one call; the plaintext never leaves the platform. Use it after a key rotation, and for ciphertexts that decrypt answers with `K9O_SEALED_UNDER_RETIRED_KEY`. Send the same `crypt` and `context` used to encrypt. Returns `items` in order; each is a new base64 `ciphertext` or a failure `{ code, message, context }`, as for decrypt.

Requires the `crypto` rewrap permission on the crypt (project editors and admins by default), held through project membership: an org role alone does not count.

Who can call it:
- A service token created with this crypt in its `crypts`.
- A workload whose bound policy allows it on this crypt.
- A personal access token scoped to resource class `crypto` and this crypt (minting one requires step-up).
- A signed-in session that completes a step-up for this crypt and operation, one proof per call (the first request answers 401 `K9O_STEP_UP_REQUIRED` with the challenge; retry it with the proof).

An unscoped personal access token is refused (`crypto_requires_scoped_pat`). A call that ran answers 200, even if some or all of its items failed.

This API serves platform-managed keys. A project whose key is held in your own cloud KMS gets 409 `K9O_ZK_STORE_FLOW_REQUIRED` for the whole call: use the SDK's client-side `kibo.encrypt` / `kibo.decrypt`, which call your KMS directly. Under self-deployed hold-your-own-key custody the key operations run in your HSM, so calls take longer, and an HSM that cannot be reached fails the whole call.

## Parameters

| Name | In | Required | Description |
|---|---|---|---|
| `projectSlug` | path | yes | The project's slug: the path segment after `@`. It is unique within the org. Example: `"storefront"`. |

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `crypt` | string | yes | The crypt: the authorisation unit, bound into the ciphertext |
| `items` | array of object | yes | The values to process, 1 to 100. Each is handled on its own, and the answer has one entry per item, in the same order. |
| `items.[]ciphertext` | string | yes | A ciphertext from this resource, standard base64 |
| `items.[]context` | string | no | Optional caller-chosen context, at most 256 bytes; the same value is needed to decrypt |

```json
{
  "crypt": "customer-pii",
  "items": [
    {
      "ciphertext": "AQEB…",
      "context": "user:usr_8f2k"
    }
  ]
}
```

## Responses

- **200**: Success

| Field | Type | Required | Description |
|---|---|---|---|
| `data` | object | yes | The result for each item. |
| `data.items` | array of object | yes | One entry per request item, in order. The call is 200 whether some or all items failed. |
| _one of_ | | |  |
| `data.items.[]ciphertext` | string | yes | standard base64 |
| _or_ | | |  |
| `data.items.[]code` | string | yes | K9O_ENVELOPE_INTEGRITY_FAILURE (cannot be opened; no further detail) or K9O_SEALED_UNDER_RETIRED_KEY (rewrap it) |
| `data.items.[]message` | string | yes | A readable explanation of `code`, for logs. Branch on `code`, not on this text. |
| `data.items.[]context` | object | yes | Empty, except resealableUntil on K9O_SEALED_UNDER_RETIRED_KEY |
| `meta` | object | yes |  |


## Errors

| HTTP | Code | When |
|---|---|---|
| 400 | `K9O_INVALID_FIELD_VALUE` | The body is not exactly { crypt, items }, crypt does not match ^[a-z0-9-]{1,64}$, items is not 1 to 100 objects of the expected field and an optional context, a value is not standard base64, or a context is over 256 bytes. |
| 401 | `K9O_UNAUTHENTICATED` | The caller is not authenticated. |
| 403 | `K9O_ACCESS_DENIED` | The caller is not an accepted member of this project (an org role alone does not count). context.reason `crypto_requires_scoped_pat`: a personal access token not scoped to resource class `crypto` and this call's crypts. context.reason `crypt_not_provisioned`: a service token whose `crypts` do not include this crypt. |
| 403 | `K9O_IAM_POLICY_DENIED` | The caller's policy does not allow this crypto action on this crypt. |
| 403 | `K9O_EXTENSION_PERMISSION_DENIED` | Extensions use k9o.kibo.encrypt and k9o.kibo.decrypt instead. |
| 403 | `K9O_RBAC_DENY` | End users cannot call this API. |
| 410 | `K9O_PROJECT_ZEROIZED` | The project's key has been zeroized; nothing can be sealed or opened under it. |
| 413 | `K9O_PAYLOAD_TOO_LARGE` | An item is over 64 KiB, or the call is over 1 MiB (context.scope says which). |
| 429 | `K9O_RATE_LIMITED` | The project is over its rate of crypto items; retry after the Retry-After seconds. |
| 503 | `K9O_KEY_SERVICE_UNAVAILABLE` | The key service could not complete the call. Nothing was returned; retry. |
| 503 | `K9O_BYOK_KEY_UNREACHABLE` | The project's cloud KMS key cannot be reached. |
| 503 | `K9O_HYOK_CLUSTER_UNREACHABLE` | No host of the project's HSM cluster can be reached. |
| 403 | `K9O_PAT_COLLECTION_NOT_PERMITTED` | The personal access token is scoped to other `crypto` crypts. |
| 401 | `K9O_STEP_UP_REQUIRED` | A signed-in session must complete a step-up for this crypt and operation; context.stepUp carries the challenge. Retry the same request with the proof. |
| 401 | `K9O_STEP_UP_PROOF_MALFORMED` | The step-up proof was rejected (including a proof already used). |
| 409 | `K9O_ZK_STORE_FLOW_REQUIRED` | This project's key is held in your own KMS (bring or hold your own key, managed by the platform). This API serves platform-managed keys only; use the SDK's client-side kibo.encrypt / kibo.decrypt, which call your KMS directly. The whole call is refused; no item is processed.

The response `context` is:

```
{ route: "client", custodyMode?: "PLATFORM_MANAGED" \| "SKR" \| "BYOK" \| "HYOK" }
```

custodyMode is the project's custody mode, left out when it is not known. recommendation: { action } says the same in words. |

## Code samples

### cURL

```bash
curl -X POST 'https://<org>.api-<region>.k9o.io/@storefront/crypto/rewrap' \
  -H 'Authorization: Bearer $K9O_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "crypt": "customer-pii",
  "items": [
    {
      "ciphertext": "AQEB…",
      "context": "user:usr_8f2k"
    }
  ]
}'
```

### fetch

```javascript
const res = await fetch('https://<org>.api-<region>.k9o.io/@storefront/crypto/rewrap', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.K9O_TOKEN}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "crypt": "customer-pii",
  "items": [
    {
      "ciphertext": "AQEB…",
      "context": "user:usr_8f2k"
    }
  ]
}),
});
const { data, meta } = await res.json();
```

### k9o CLI

```bash
k9o crypto rewrap --crypt <crypt>
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.rewrap({
  crypt: 'customer-pii',
  items: [{
    ciphertext: 'AQEB…',
    context: 'user:usr_8f2k'
  }]
})
```

### k9o

```python
# k9o = create_client(org_slug="playground", project_slug="storefront", api_key="k9o_…")
response = k9o.crypto.rewrap({
    "crypt": "customer-pii",
    "items": [{
        "ciphertext": "AQEB…",
        "context": "user:usr_8f2k"
    }]
})
```

### sdk-go

```go
// ctx := context.Background()
// client, _ := k9o.NewClient(k9o.ClientOpts{OrgSlug: "playground", ProjectSlug: "storefront", APIKey: "k9o_…"})
data, _, kerr := client.Crypto.Rewrap(ctx, map[string]any{"crypt": "customer-pii", "items": []any{map[string]any{"ciphertext": "AQEB…", "context": "user:usr_8f2k"}}})
```

### k9o

```rust
// let k9o = Client::new(ClientOpts { org_slug: "playground".into(), project_slug: "storefront".into(), api_key: "k9o_…".into() })?;
let resp = k9o.crypto.rewrap(json!({"crypt": "customer-pii", "items": [json!({"ciphertext": "AQEB…", "context": "user:usr_8f2k"})]})).await?
```

### dev.k9o:core

```java
// K9o k9o = K9o.createClient(K9o.Opts.builder().orgSlug("playground").projectSlug("storefront").apiKey("k9o_…").build());
var response = k9o.crypto().rewrap(Map.of("crypt", "customer-pii", "items", List.of(Map.of("ciphertext", "AQEB…", "context", "user:usr_8f2k"))))
```

### K9o.Core

```c#
// var k9o = K9oClient.Create(new K9oOptions { OrgSlug = "playground", ProjectSlug = "storefront", ApiKey = "k9o_…" });
var response = await k9o.Crypto.RewrapAsync(new Dictionary<string, object> { ["crypt"] = "customer-pii", ["items"] = new object[] { new Dictionary<string, object> { ["ciphertext"] = "AQEB…", ["context"] = "user:usr_8f2k" } } })
```

### k9o

```ruby
# k9o = K9o.create_client(org_slug: "playground", project_slug: "storefront", api_key: "k9o_…")
response = k9o.crypto.rewrap({ crypt: "customer-pii", items: [{ ciphertext: "AQEB…", context: "user:usr_8f2k" }] })
```

### k9o/sdk

```php
// $k9o = K9oClient::create(['org_slug' => 'playground', 'project_slug' => 'storefront', 'api_key' => 'k9o_…']);
$response = $k9o->crypto->rewrap(['crypt' => 'customer-pii', 'items' => [['ciphertext' => 'AQEB…', 'context' => 'user:usr_8f2k']]])
```


Canonical page: https://docs.kilimanjaro.dev/api-playground/core/rewrap
