# Decrypt

`POST /crypto/decrypt` · Core · Encryption

Decrypts up to 100 ciphertexts made by this API, with the same `crypt` and `context` used to encrypt them. Returns `items` in order; each is either a base64 `plaintext` or a failure `{ code, message, context }`:
- `K9O_ENVELOPE_INTEGRITY_FAILURE`, with no further detail, for anything that cannot be opened (a different crypt or context, a changed or malformed ciphertext, another project's).
- `K9O_SEALED_UNDER_RETIRED_KEY` for a ciphertext sealed under a key that has since been retired (rewrap it while `context.resealableUntil` allows).

If the project has moved to its own KMS, a ciphertext still sealed under the old platform key opens until its deadline, and its item also carries `resealableUntil`: re-seal it client-side before then.

Requires the `crypto` decrypt 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.

Ciphertext from this API cannot be opened by client-side Kibo or by an extension's `k9o.kibo.encrypt`, and theirs cannot be opened here.

## 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.[]plaintext` | string | yes | standard base64 |
| `data.items.[]resealableUntil` | string (date-time) | no | Present only when the project moved to its own KMS and this ciphertext is still sealed under the old platform key: re-seal it client-side before this time, after which it can no longer be opened. |
| _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/decrypt' \
  -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/decrypt', {
  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 decrypt --crypt <crypt>
```

### @k9o/core

```typescript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.crypto.decrypt({
  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.decrypt({
    "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.Decrypt(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.decrypt(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().decrypt(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.DecryptAsync(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.decrypt({ 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->decrypt(['crypt' => 'customer-pii', 'items' => [['ciphertext' => 'AQEB…', 'context' => 'user:usr_8f2k']]])
```


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