> For the complete documentation index, see [llms.txt](https://docs.toolkit.equs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.toolkit.equs.ai/api/web-wallet-api/decryption.md).

# Decryption

## Decrypt a holder payload (Service Provider / Tenant)

> Endpoint for Service Provider or Tenant. Decrypts a compact JWE on behalf of the holder named by userId and returns the plaintext re-encrypted to the supplied senderEpk.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Web Custodial Wallet Documentation","version":"0.1.2"},"tags":[{"name":"Decryption","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateDecryptionRequestRequest":{"type":"object","properties":{"payload":{"type":"string","description":"Compact JWE encrypted to the holder keyAgreement public key"},"senderEpk":{"description":"Ephemeral P-256 public JWK the result is encrypted to","allOf":[{"$ref":"#/components/schemas/SenderEphemeralPublicKey"}]},"userId":{"type":"string","description":"User unique ID"}},"required":["payload","senderEpk","userId"]},"SenderEphemeralPublicKey":{"type":"object","properties":{"kty":{"type":"string","description":"Key type of the sender ephemeral public key.","enum":["EC"]},"crv":{"type":"string","description":"Elliptic curve of the sender ephemeral public key.","enum":["P-256"]},"x":{"type":"string","description":"Base64url-encoded X coordinate"},"y":{"type":"string","description":"Base64url-encoded Y coordinate"},"kid":{"type":"string","description":"Key identifier echoed into the result JWE header"}},"required":["kty","crv","x","y"]}}},"paths":{"/api/v1/decryption/requests":{"post":{"description":"Endpoint for Service Provider or Tenant. Decrypts a compact JWE on behalf of the holder named by userId and returns the plaintext re-encrypted to the supplied senderEpk.","operationId":"DecryptionController_decrypt_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDecryptionRequestRequest"}}}},"responses":{"200":{"description":"Payload decrypted and re-encrypted to senderEpk"},"400":{"description":"- Request validation failed; `message` lists the offending fields\n- `invalid_jwe_parameters` (in `code`) — the JWE protected header is missing or declares an unsupported `alg`, `enc`, `kid`, `epk`, `apu`, `apv` or `encrypted_key`\n- `payload_kid_mismatch` — the payload was encrypted to a key other than the holder current keyAgreement key\n- `decryption_failed` (with `code: DECRYPTION`) — the payload could not be decrypted. Also returned when the key store itself fails"},"401":{"description":"Missing or invalid agents-realm service token"},"404":{"description":"- `no_did` — no holder identity exists for this user\n- `no_key_agreement` — the holder DID document has no usable keyAgreement verification method\n- `key_agreement_kid_missing` — the holder keyAgreement method exposes no kid\n- `key_unavailable` — the holder key could not be resolved from the key store"},"500":{"description":"- `key_unavailable` — the holder key could not be resolved from the key store\n- `unexpected_error` — unhandled failure"}},"summary":"Decrypt a holder payload (Service Provider / Tenant)","tags":["Decryption"]}}}}
```

## Decrypt own payload (Holder)

> Holder endpoint. Decrypts a JWE encrypted to the caller keyAgreement key and re-encrypts the plaintext to the supplied senderEpk. The holder is derived from the token. Agents use the Service Provider endpoint.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Web Custodial Wallet Documentation","version":"0.1.2"},"tags":[{"name":"Decryption","description":""}],"security":[{"user":[]}],"components":{"securitySchemes":{"user":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Holder user. `users` realm token with `principal_type=user`. Authorize one bearer scheme at a time."}},"schemas":{"CreateUserDecryptionRequestRequest":{"type":"object","properties":{"payload":{"type":"string","description":"Compact JWE encrypted to the holder keyAgreement public key"},"senderEpk":{"description":"Ephemeral P-256 public JWK the result is encrypted to","allOf":[{"$ref":"#/components/schemas/SenderEphemeralPublicKey"}]}},"required":["payload","senderEpk"]},"SenderEphemeralPublicKey":{"type":"object","properties":{"kty":{"type":"string","description":"Key type of the sender ephemeral public key.","enum":["EC"]},"crv":{"type":"string","description":"Elliptic curve of the sender ephemeral public key.","enum":["P-256"]},"x":{"type":"string","description":"Base64url-encoded X coordinate"},"y":{"type":"string","description":"Base64url-encoded Y coordinate"},"kid":{"type":"string","description":"Key identifier echoed into the result JWE header"}},"required":["kty","crv","x","y"]}}},"paths":{"/api/v1/decryption/requests/user":{"post":{"description":"Holder endpoint. Decrypts a JWE encrypted to the caller keyAgreement key and re-encrypts the plaintext to the supplied senderEpk. The holder is derived from the token. Agents use the Service Provider endpoint.","operationId":"DecryptionController_decryptForHolder_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserDecryptionRequestRequest"}}}},"responses":{"200":{"description":"Payload decrypted and re-encrypted to senderEpk"},"400":{"description":"- Request validation failed; `message` lists the offending fields\n- `invalid_jwe_parameters` (in `code`) — the JWE protected header is missing or declares an unsupported `alg`, `enc`, `kid`, `epk`, `apu`, `apv` or `encrypted_key`\n- `payload_kid_mismatch` — the payload was encrypted to a key other than the holder current keyAgreement key\n- `decryption_failed` (with `code: DECRYPTION`) — the payload could not be decrypted. Also returned when the key store itself fails"},"401":{"description":"Missing or invalid holder token"},"404":{"description":"- `no_did` — no holder identity exists for this user\n- `no_key_agreement` — the holder DID document has no usable keyAgreement verification method\n- `key_agreement_kid_missing` — the holder keyAgreement method exposes no kid\n- `key_unavailable` — the holder key could not be resolved from the key store"},"500":{"description":"- `key_unavailable` — the holder key could not be resolved from the key store\n- `unexpected_error` — unhandled failure"}},"summary":"Decrypt own payload (Holder)","tags":["Decryption"]}}}}
```

## Decrypt multiple payloads (Service Provider / Tenant)

> Endpoint for Service Provider or Tenant. Decrypts a batch of compact JWEs, each on behalf of the user named by its userId, and returns every plaintext re-encrypted to its supplied senderEpk. Items are processed independently; a failing item is reported without aborting the batch.

```json
{"openapi":"3.0.0","info":{"title":"EqusDTK Web Custodial Wallet Documentation","version":"0.1.2"},"tags":[{"name":"Decryption","description":""}],"security":[{"sp":[]},{"tenant":[]},{"sp":[]}],"components":{"securitySchemes":{"sp":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Service Provider. Token of the Service Provider client in the `agents` realm, with no `tenantId` claim. Authorize one bearer scheme at a time."},"tenant":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Tenant. Token of a Tenant machine client or of a Tenant portal user, carrying the `tenantId` claim. Authorize one bearer scheme at a time."}},"schemas":{"CreateDecryptionRequestsRequest":{"type":"object","properties":{"requests":{"description":"Decryption requests to process","type":"array","items":{"$ref":"#/components/schemas/CreateDecryptionRequestRequest"}}},"required":["requests"]},"CreateDecryptionRequestRequest":{"type":"object","properties":{"payload":{"type":"string","description":"Compact JWE encrypted to the holder keyAgreement public key"},"senderEpk":{"description":"Ephemeral P-256 public JWK the result is encrypted to","allOf":[{"$ref":"#/components/schemas/SenderEphemeralPublicKey"}]},"userId":{"type":"string","description":"User unique ID"}},"required":["payload","senderEpk","userId"]},"SenderEphemeralPublicKey":{"type":"object","properties":{"kty":{"type":"string","description":"Key type of the sender ephemeral public key.","enum":["EC"]},"crv":{"type":"string","description":"Elliptic curve of the sender ephemeral public key.","enum":["P-256"]},"x":{"type":"string","description":"Base64url-encoded X coordinate"},"y":{"type":"string","description":"Base64url-encoded Y coordinate"},"kid":{"type":"string","description":"Key identifier echoed into the result JWE header"}},"required":["kty","crv","x","y"]}}},"paths":{"/api/v1/decryption/requests/batch":{"post":{"description":"Endpoint for Service Provider or Tenant. Decrypts a batch of compact JWEs, each on behalf of the user named by its userId, and returns every plaintext re-encrypted to its supplied senderEpk. Items are processed independently; a failing item is reported without aborting the batch.","operationId":"DecryptionController_decryptMany_api/v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateDecryptionRequestsRequest"}}}},"responses":{"200":{"description":"Per-item decryption results, in request order; each entry reports success or an error code. A failed item never changes the HTTP status"},"400":{"description":"Request validation failed (e.g. an empty list, more than 100 items, or an invalid item)"},"401":{"description":"Missing or invalid agents-realm service token"},"500":{"description":"`unexpected_error` — unhandled failure"},"503":{"description":"`service_overloaded` — the instance is saturated and is shedding batch requests. The whole batch is rejected, nothing was decrypted; retry with exponential backoff"}},"summary":"Decrypt multiple payloads (Service Provider / Tenant)","tags":["Decryption"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.toolkit.equs.ai/api/web-wallet-api/decryption.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.