---
url: /apidocs/encryption.md
---
## Encryption API

| Endpoint | Method | Description |
|-----|-----|-----|
| [encryption:getZAddressForUser](#get-z-address-for-user) | websocket | Get z address for user |
| [encryption:createEpoch](#create-encryption-epoch) | websocket | Create encryption epoch |
| [encryption:updateEpoch](#update-encryption-epoch) | websocket | Update encryption epoch |
| [encryption:setEpochOwner](#set-encryption-epoch-owner) | websocket | Set encryption epoch owner |
| [encryption:listEpoches](#list-encryption-epoches) | websocket | List encryption epoches |
| [encryption:listEpochesByTuples](#list-encryption-epoches-by-tuples) | websocket | List encryption epoches by tuples |
| [encryption:listEpochesByZAddress](#list-encryption-epoches-by-z-address) | websocket | List encryption epoches by z address |
| [encryption:getLastEpoch](#get-last-encryption-epoch) | websocket | Get last encryption epoch |
| ~~[encryption:getEpochChain](#get-encryption-epoch-chain)~~ | websocket | Get encryption epoch chain |
| [encryption:getEpochChainPerKey](#get-encryption-epoch-chain-per-key) | websocket | Get encryption epoch chain per key |
| [encryption:getEpochChainForKey](#get-encryption-epoch-chain-for-key) | websocket | Get encryption epoch chain for key |
| [encryption:requestEncryption](#request-encryption) | websocket | Request encryption |
| [encryption:setRequestedEncryption](#set-requested-encryption) | websocket | Set requested encryption |
| [encryption:onEpochCreated](#on-encryption-epoch-created-event) | websocketEvent | On encryption epoch created event |
| [encryption:onEncryptionRequested](#on-encryption-requested-event) | websocketEvent | On encryption requested event |

### Get z address for user

**Method:** websocket

**Endpoint:** encryption:getZAddressForUser

**Description:** Api returns z-addresses of target user in order to encrypt viewing keys for him.

**Request:**

**Response:**

### Create encryption epoch

**Method:** websocket

**Endpoint:** encryption:createEpoch

**Description:** Api creates new epoch for target item encryption. Epoch initiator should create viewing key and encrypt it for zAddresses of each owner. Multiple keys could form a keychain that is used to decrypt the target (like resource<-channel<-user). Only users who have viewing key for an epoch (or to keychain root) will be able to decrypt cypher data.

List of valid encryption target types:

* `channel` (use channelId as targetId)
* `resource` (use resourceId as targetId)
* `room` (use roomId as targetId)
* `identitySellOffer` (use userId:identityKey as targetId)
* `identityBuyOffer` (use offerId as targetId)

List of valid encryption owner types:

* `user` (use userId as ownerId)
* `channel` (use channelId as ownerId)
* `resource` (use resourceId as ownerId)
* `room` (use roomId as ownerId)
* `aiAgent` (use userId:agentId as ownerId)
* `identityBuyOffer` (use offerId as ownerId)

**Request:**

**Response:**

### Update encryption epoch

**Method:** websocket

**Endpoint:** encryption:updateEpoch

**Description:** Api updates encryption epoch for owner. This is useful in case when user has changed his zAddress and wants to update viewing keys correspondingly.

**Request:**

**Response:**

### Set encryption epoch owner

**Method:** websocket

**Endpoint:** encryption:setEpochOwner

**Description:** Api sets new owner for an encryption epoch. This api should be used to share encrypted target with a new owner (user, channel, room, etc...).

**Request:**

**Response:**

### List encryption epoches

**Method:** websocket

**Endpoint:** encryption:listEpoches

**Description:** Api returns latest encryption epoches (with owner context) for provided targetId.

**Request:**

**Response:**

### List encryption epoches by tuples

**Method:** websocket

**Endpoint:** encryption:listEpochesByTuples

**Description:** Api returns encryption epoches (with owner context) for provided targetId-epoch tuples.

**Request:**

**Response:**

### List encryption epoches by z address

**Method:** websocket

**Endpoint:** encryption:listEpochesByZAddress

**Description:** Api returns encryption epoches (with owner context) for provided owner zAddress.

**Request:**

**Response:**

### Get last encryption epoch

**Method:** websocket

**Endpoint:** encryption:getLastEpoch

**Description:** Api returns last encryption epoch for provided targetId.

**Request:**

**Response:**

### Get encryption epoch chain

**Method:** websocket

**Endpoint:** encryption:getEpochChain

**DEPRECATED**

**Description:** Api returns list of epoches by provided tuples + parent epoches that are required to build encryption context chain.

**Request:**

**Response:**

### Get encryption epoch chain per key

**Method:** websocket

**Endpoint:** encryption:getEpochChainPerKey

**Description:** Api returns encryption epoch chains for given epoch keys, split per key. Each key in the response maps to the ordered list of epoches needed to decrypt that specific object. Keys with no accessible chain are included with an empty list.

**Request:**

**Response:**

### Get encryption epoch chain for key

**Method:** websocket

**Endpoint:** encryption:getEpochChainForKey

**Description:** Api returns encryption epoch chain for a single epoch key. Returns the ordered list of epoches needed to decrypt the object.

**Request:**

**Response:**

### Request encryption

**Method:** websocket

**Endpoint:** encryption:requestEncryption

**Description:** Api requests an encryption key for a target item on behalf of the caller (typically an AI agent). Server notifies all existing epoch owners who can then fulfill the request via setRequestedEncryption.

**Request:**

**Response:**

### Set requested encryption

**Method:** websocket

**Endpoint:** encryption:setRequestedEncryption

**Description:** Api fulfills a pending encryption key request by adding a new epoch owner. Once fulfilled, the requester receives an onEpochCreated event with the new viewing key.

**Request:**

**Response:**

### On encryption epoch created event

**Event:** encryption:onEpochCreated

**Description:** Event is triggered when new epoch is created.

**Data:**

### On encryption requested event

**Event:** encryption:onEncryptionRequested

**Description:** Event is triggered when new encryption key is requested for an epoch.

**Data:**