Encryption API

Endpoint	Method	Description
encryption:getZAddressForUser	websocket	Get z address for user
encryption:createEpoch	websocket	Create encryption epoch
encryption:updateEpoch	websocket	Update encryption epoch
encryption:setEpochOwner	websocket	Set encryption epoch owner
encryption:listEpoches	websocket	List encryption epoches
encryption:listEpochesByTuples	websocket	List encryption epoches by tuples
encryption:listEpochesByZAddress	websocket	List encryption epoches by z address
encryption:getLastEpoch	websocket	Get last encryption epoch
encryption:getEpochChain	websocket	Get encryption epoch chain
encryption:getEpochChainPerKey	websocket	Get encryption epoch chain per key
encryption:getEpochChainForKey	websocket	Get encryption epoch chain for key
encryption:requestEncryption	websocket	Request encryption
encryption:setRequestedEncryption	websocket	Set requested encryption
encryption:onEpochCreated	websocketEvent	On encryption epoch created event
encryption:onEncryptionRequested	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:

{
    "data": {
        "targetUser": string
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "zAddress": string
    }
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "targetZAddress": string  // zAddress of encryption target for current epoch
        "targetType": string  // type of encryption target, like 'channel' or 'resource'
        "ownerKeys": [{  // viewing keys for epoch
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
        "expectedEpoch": int  // optional, if provided - server will check that new epoch equals to expectedEpoch (detect simultaneous epoch creation)
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoch": {
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "epoch": int  // encryption epoch to update
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner for current epoch
        "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
        "vkCypher": string  // viewing key of encryption owner for current epoch
        "vkEpk": string  // ephemeral public key for viewing key decryption
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "accessId": string  // check permission using accessId in case when no direct permissions for targetId
        "epoch": int  // encryption epoch to update
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner for current epoch
        "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
        "vkCypher": string  // viewing key of encryption owner for current epoch
        "vkEpk": string  // ephemeral public key for viewing key decryption
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

List encryption epoches

Method: websocket

Endpoint: encryption:listEpoches

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

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "targetId": string  // encryption target id, like channelId or resourceId
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

List encryption epoches by tuples

Method: websocket

Endpoint: encryption:listEpochesByTuples

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

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "epochTuples": [ ( targetId string, epoch int ) ]  // list of [targetId, epoch] tuples to fetch
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

List encryption epoches by z address

Method: websocket

Endpoint: encryption:listEpochesByZAddress

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

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

Get last encryption epoch

Method: websocket

Endpoint: encryption:getLastEpoch

Description: Api returns last encryption epoch for provided targetId.

Request:

{
    "data": {
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "targetId": string  // encryption target id, like channelId or resourceId
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoch": {
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }
    }
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "epochTuples": [ ( targetId string, epoch int ) ]  // list of [targetId, epoch] tuples
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "epochKeys": [ string ]  // list of epochKey strings (format: 'epochNumber:targetId')
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": map[string][{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "epochKey": string  // epochKey string (format: 'epochNumber:targetId')
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "data": {
        "epoches": [{
            "epochKey": string  // epoch:targetId
            "targetId": string  // encryption target id, like channelId or resourceId
            "targetZAddress": string  // zAddress of encryption target for current epoch
            "targetType": string  // type of encryption target, like 'channel' or 'resource'
            "epoch": int  // encryption epoch number
            "created": timestamp  // epoch creation time
            "ownerId": string  // encryption owner id, like userId, directoryId or roomId
            "ownerZAddress": string  // zAddress of encryption owner for current epoch
            "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
            "vkCypher": string  // viewing key of encryption owner for current epoch
            "vkEpk": string  // ephemeral public key for viewing key decryption
        }]
    }
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "targetType": string  // channel
        "targetId": string  // channelId
        "epoch": int  // encryption epoch to update
        "ownerType": string  // aiAgent
        "ownerId": string  // userId:agentId
        "ownerZAddress": string  // zAddress generated from agent scoped root key
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

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:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "epoch": int  // encryption epoch to update
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner for current epoch
        "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
        "vkCypher": string  // viewing key of encryption owner for current epoch
        "vkEpk": string  // ephemeral public key for viewing key decryption
    }
    "event": { "id": string, "date": timestamp }
}

Response:

{
    "error": { "status": bool, "code": int, "message": string }
}

On encryption epoch created event

Event: encryption:onEpochCreated

Description: Event is triggered when new epoch is created.

Data:

{
    "data": {
        "epochKey": string  // epoch:targetId
        "targetId": string  // encryption target id, like channelId or resourceId
        "targetZAddress": string  // zAddress of encryption target for current epoch
        "targetType": string  // type of encryption target, like 'channel' or 'resource'
        "epoch": int  // encryption epoch number
        "created": timestamp  // epoch creation time
        "ownerId": string  // encryption owner id, like userId, directoryId or roomId
        "ownerZAddress": string  // zAddress of encryption owner for current epoch
        "ownerType": string  // type of encryption owner, like 'user', 'channel', 'resource' or 'room'
        "vkCypher": string  // viewing key of encryption owner for current epoch
        "vkEpk": string  // ephemeral public key for viewing key decryption
    }
    "error": { "status": bool, "code": int, "message": string }
}

On encryption requested event

Event: encryption:onEncryptionRequested

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

Data:

{
    "data": {
        "targetId": string  // encryption target id, like channelId or resourceId
        "targetType": string  // type of encryption target, like 'channel' or 'resource'
        "epoch": int  // encryption epoch number
        "created": timestamp  // request creation time
        "requestOwnerId": string  // encryption owner id, like userId or userId:agentId
        "requestOwnerZAddress": string  // zAddress of encryption owner for current epoch
        "requestOwnerType": string  // type of encryption owner, like 'user' or 'aiAgent'
        "recipientId": string  // recipient (userId) who should update encryption epoch for key owner
    }
    "error": { "status": bool, "code": int, "message": string }
}