Commands

Contents

Commands#

List all the actions you can perform with your Olvid identity, using daemon APi.

Message Command Service#

Info

Associated Datatype: Message

MessageList#

List messages for current identity.
Pass a filter to select only messages that match specific criteria.
You can list unread only messages with unread parameter. This is useful to list unread messages on start if you want to process messages that arrived when you were down.
Messages are mark as read when you list them with MessageList or if a MessageReceived notification was sent to any client when it arrived.

Request: MessageListRequest

  • filter (optional MessageFilter)

  • unread (optional bool - only list unread messages (messages that have never been listed or sent in a MessageReceived notification))

Response (Stream): MessageListResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • INVALID_ARGUMENT: filter is invalid

  • INTERNAL

MessageGet#

get a specific message by id.

Request: MessageGetRequest

Response: MessageGetResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: message not found.

MessageSend#

Post a text message in a discussion.
A message must have a non-blank body.

Request: MessageSendRequest

  • discussion_id (uint64 - the discussion to post the message into)

  • body (string - text body for the message)

  • reply_id (optional MessageId - the id of a message to quote)

  • ephemerality (optional MessageEphemerality - set an ephemerality for this message)

  • disable_link_preview (optional bool - do not download link preview if a link is detected in the message body (make send process faster))

Response: MessageSendResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: discussion / replied message not found.

  • INVALID_ARGUMENT: message body is empty or blank.

  • INTERNAL

MessageSendWithAttachments#

Post a message with attachments in a given discussion.
A message must have a non empty body or at least one attachment.
To allow sending multiple files with no size limitations this entry point is a client stream.
First send a MessageSendWithAttachmentsRequest filling metadata field.
Then send each file separately by chunks of any size.
Always send an empty MessageSendWithAttachmentsRequest with only file_delimiter set to true at the end of each file upload.
Once attachments uploaded finished daemon will answer with a response and close stream.

Request (Stream): MessageSendWithAttachmentsRequest

Response: MessageSendWithAttachmentsResponse

  • message (Message - sent message)

  • attachments (repeated Attachment - sent attachments)

MessageSendWithAttachmentsRequestMetadata

Fields:

  • discussion_id (uint64 - the discussion to post the message into)

  • body (optional string - text body, mandatory if there are no attached files)

  • reply_id (optional MessageId - the id of a message to quote)

  • ephemerality (optional MessageEphemerality - set an ephemerality for message and attachments)

  • disable_link_preview (optional bool - do not download link preview if a link is detected in the message body (make send process faster))

  • files (repeated MessageSendWithAttachmentsRequestMetadata.File - a list of files to attach to the message)

MessageSendWithAttachmentsRequestMetadata.File

describe a file you want to attach to a message

Fields:

  • filename (string)

  • file_size (uint64 - file size in bytes)

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: discussion / replied message not found.

  • INVALID_ARGUMENT: message body is empty or blank with no attached file / attached the same file twice.

  • INTERNAL

MessageReact#

Add, update or remove a reaction from a message.
If reaction is set this will add a new reaction or update your previous reaction on this message.
If reaction is an empty string your previous reaction will be removed if you had one.

Request: MessageReactRequest

  • message_id (MessageId - the message to react)

  • reaction (optional string - an emoji string)

Response: MessageReactResponse

  • Empty payload.

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: message not found.

  • INTERNAL

MessageUpdateBody#

Update one of your message body.
Body cannot be empty or blank.

Request: MessageUpdateBodyRequest

  • message_id (MessageId - the message to update)

  • updated_body (string - the new body)

Response: MessageUpdateBodyResponse

  • Empty payload.

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: message not found.

  • INVALID_ARGUMENT: you can only edit your own messages / new body cannot be empty or blank.

  • INTERNAL

MessageDelete#

Delete a message giving its id.
If delete_everywhere is specified, the message (and associated attachments) will be deleted on every other participant devices.
delete_everywhere is only allowed in certain circumstances.
For one to one discussions:

  • inbound message: you cannot remote delete your contact messages

  • outbound message: you can always remote delete your own messages
    For group discussions:

  • inbound message: you must have remote_delete_anything permission

  • outbound message: you must have remote_delete_anything or edit_or_remote_delete_own_messages permission.

Request: MessageDeleteRequest

  • message_id (MessageId)

  • delete_everywhere (optional bool)

Response: MessageDeleteResponse

  • Empty payload.

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: message not found.

  • INVALID_ARGUMENT: cannot delete everywhere this message

  • INTERNAL

MessageSendLocation#

Post a location message in a discussion.
A location message represents a specific location, and is different from a location sharing that can be updated later.

Request: MessageSendLocationRequest

  • discussion_id (uint64)

  • latitude (double)

  • longitude (double)

  • altitude (optional double)

  • precision (optional float)

  • address (optional string)

  • preview_filename (optional string - attach an option preview as a picture, specify filename to use)

  • preview_payload (optional bytes - attach an option preview as a picture, specify payload (must be smaller than grpc max message size))

  • ephemerality (optional MessageEphemerality - make your location message ephemeral)

Response: MessageSendLocationResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: discussion not found.

  • INVALID_ARGUMENT: latitude and longitude are both equal to zero / preview_filename and preview_payload must be set together.

  • INTERNAL

MessageStartLocationSharing#

Start sharing a location in a discussion.

Request: MessageStartLocationSharingRequest

  • discussion_id (uint64)

  • latitude (double)

  • longitude (double)

  • altitude (optional double)

  • precision (optional float)

Response: MessageStartLocationSharingResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: discussion not found.

  • INVALID_ARGUMENT: latitude and longitude are both equal to zero.

  • INTERNAL

MessageUpdateLocationSharing#

Update one of your sharing location message with a new location.

Request: MessageUpdateLocationSharingRequest

  • message_id (MessageId)

  • latitude (double)

  • longitude (double)

  • altitude (optional double)

  • precision (optional float)

Response: MessageUpdateLocationSharingResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: message not found.

  • INVALID_ARGUMENT: you can only update your location sharing messages / sharing is no longer active.

  • INTERNAL

MessageEndLocationSharing#

Request: MessageEndLocationSharingRequest

Response: MessageEndLocationSharingResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • NOT_FOUND: message not found.

  • INVALID_ARGUMENT: you can only end your location sharing messages / sharing is no longer active.

  • INTERNAL

MessageRefresh#

Manually refresh messages available on server.

Request: MessageRefreshRequest

  • Empty payload.

Response: MessageRefreshResponse

  • Empty payload.

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

Attachment Command Service#

Info

Associated Datatype: Attachment

AttachmentList#

List attachments for current identity.
Pass a filter to select only attachments that match specific criteria.

Request: AttachmentListRequest

Response (Stream): AttachmentListResponse

Error Codes:

  • NOT_FOUND (“Message not found”): filter.messageId does not belong to an identity message.

  • UNAUTHENTICATED: client key is invalid.

AttachmentGet#

Get an attachment by id.

Request: AttachmentGetRequest

Response: AttachmentGetResponse

Error Codes:

  • NOT_FOUND (Attachment not found): attachment_id does not belong to an identity attachment.

  • UNAUTHENTICATED: client key is invalid.

AttachmentDelete#

Delete an attachment by id.
Use this to delete attachment and associated file locally to save space.
Else message deletion implies associated attachments deletion.

Request: AttachmentDeleteRequest

Response: AttachmentDeleteResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND (Attachment not found): attachment_id does not belong to an identity attachment.

  • UNAUTHENTICATED: client key is invalid.

AttachmentDownload#

Download the file associated to an attachment.
This returns one or more chunks of bytes.

Request: AttachmentDownloadRequest

Response (Stream): AttachmentDownloadResponse

  • chunk (bytes)

Error Codes:

  • NOT_FOUND (Attachment not found): attachment_id does not belong to an identity attachment.

  • INTERNAL

  • UNAUTHENTICATED: client key is invalid.

Discussion Command Service#

Info

Associated Datatype: Discussion

DiscussionList#

List discussions for current identity.
Pass a filter to select only discussions that match specific criteria.

Request: DiscussionListRequest

Response (Stream): DiscussionListResponse

Error Codes:

  • INVALID_ARGUMENT: invalid filter.

  • NOT_FOUND: filter contact not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

DiscussionGet#

Get discussion by id.

Request: DiscussionGetRequest

  • discussion_id (uint64)

Response: DiscussionGetResponse

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

DiscussionGetBytesIdentifier#

Get a discussion identifier as bytes.
This is useful to have a long term identifier for a discussion, backup-proof, and common to any device.

Request: DiscussionGetBytesIdentifierRequest

  • discussion_id (uint64)

Response: DiscussionGetBytesIdentifierResponse

  • identifier (bytes)

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

DiscussionGetByContact#

Get discussion by contact id.

Request: DiscussionGetByContactRequest

  • contact_id (uint64)

Response: DiscussionGetByContactResponse

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

DiscussionGetByGroup#

Get discussion by group id.

Request: DiscussionGetByGroupRequest

  • group_id (uint64)

Response: DiscussionGetByGroupResponse

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

DiscussionEmpty#

Delete all messages and attachments in a discussion.

Request: DiscussionEmptyRequest

  • discussion_id (uint64)

Response: DiscussionEmptyResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

DiscussionDownloadPhoto#

Download a discussion photo.
The photo can be the contact photo, the group photo, or a generated image for the discussion if a specific image was not set.
Photos are always jpeg files with a maximum of 1080x1080 resolution.

Request: DiscussionDownloadPhotoRequest

  • discussion_id (uint64)

Response: DiscussionDownloadPhotoResponse

  • photo (bytes)

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

DiscussionLockedList#

locked discussions

Request: DiscussionLockedListRequest DiscussionLockedList List locked discussions. Locked discussions are discussions associated to a deleted contact or a group you left. Messages in those discussions are still accessible, but you cannot post new messages in those discussions.

Error codes: UNAUTHENTICATED: client key is invalid. INTERNAL

  • Empty payload.

Response (Stream): DiscussionLockedListResponse

DiscussionLockedDelete#

Delete a locked discussion by id.
This will delete discussion and its content, including messages and attached files.

Request: DiscussionLockedDeleteRequest

  • discussion_id (uint64)

Response: DiscussionLockedDeleteResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: discussion not found.

  • UNAUTHENTICATED: client key is invalid.

Contact Command Service#

Info

Associated Datatype: Contact

ContactList#

List contacts for current identity.
Pass a filter to select only contacts that match specific criteria.

Request: ContactListRequest

Response (Stream): ContactListResponse

Error Codes:

  • INVALID_ARGUMENT: invalid filter.

  • UNAUTHENTICATED: client key is invalid

  • INTERNAL

ContactGet#

Get a contact by id.

Request: ContactGetRequest

  • contact_id (uint64)

Response: ContactGetResponse

Error Codes:

  • NOT_FOUND: contact not found.

  • UNAUTHENTICATED: client key is invalid.

ContactGetBytesIdentifier#

Get a contact identity as bytes.
This is useful to have a long term identifier for a contact, backup-proof, and common to any device.

Request: ContactGetBytesIdentifierRequest

  • contact_id (uint64)

Response: ContactGetBytesIdentifierResponse

  • identifier (bytes)

Error Codes:

  • NOT_FOUND: contact not found.

  • UNAUTHENTICATED: client key is invalid.

ContactDelete#

Delete a contact by id.

Request: ContactDeleteRequest

  • contact_id (uint64)

Response: ContactDeleteResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: contact not found.

  • INVALID_ARGUMENT: contact is still in a group.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

ContactIntroduction#

Introduce two of your contacts together.
They will both receive an invitation to accept.
If each of the two accepts, they will be added to each other’s contact book and can exchange.

Request: ContactIntroductionRequest

  • first_contact_id (uint64)

  • second_contact_id (uint64)

Response: ContactIntroductionResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: first or second contact not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

ContactDownloadPhoto#

Download the contact profile picture as bytes, or the group picture, or the generated image for this discussion.
Pictures are always jpeg files with a maximum of 1080x1080 resolution.

Request: ContactDownloadPhotoRequest

  • contact_id (uint64)

Response: ContactDownloadPhotoResponse

  • photo (bytes)

Error Codes:

  • NOT_FOUND: contact not found.

  • UNAUTHENTICATED: client key is invalid.

ContactRecreateChannels#

Reset cryptographic channels with a contact.
USE CAREFULLY: this might fix some issues but every non sent / received messages will be lost.

Request: ContactRecreateChannelsRequest

  • contact_id (uint64)

Response: ContactRecreateChannelsResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: contact not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

ContactInviteToOneToOneDiscussion#

collected contacts

Request: ContactInviteToOneToOneDiscussionRequest ContactInviteToOneToOneDiscussion Invite a non one-to-one contact to have a one-to-one discussion.

Error codes: NOT_FOUND: contact not found. INVALID_ARGUMENT: contact already has a one to one discussion. UNAUTHENTICATED: client key is invalid. INTERNAL

  • contact_id (uint64)

Response: ContactInviteToOneToOneDiscussionResponse

ContactDowngradeOneToOneDiscussion#

ContactDowngradeOneToOne
Downgrade a one-to-one contact to a non one-to-one contact.
This will lock current discussion with this contact.
The contact will always be in your contact book and common groups but you will no longer be able to exchange direct message.

Request: ContactDowngradeOneToOneDiscussionRequest

  • contact_id (uint64)

Response: ContactDowngradeOneToOneDiscussionResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: contact not found.

  • INVALID_ARGUMENT: contact is not one to one, does not have established channel or does not support one to one downgrade.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

Group Command Service#

Info

Associated Datatype: Group

GroupList#

List groups for current identity.
Pass a filter to select only groups that match specific criteria.

Request: GroupListRequest

Response (Stream): GroupListResponse

  • groups (repeated Group)

Error Codes:

  • INVALID_ARGUMENT: invalid filter.

  • UNAUTHENTICATED: client key is invalid.

GroupGet#

Get group by id.

Request: GroupGetRequest

  • group_id (uint64)

Response: GroupGetResponse

Error Codes:

  • NOT_FOUND: group not found.

  • UNAUTHENTICATED: client key is invalid.

GroupGetBytesIdentifier#

Get a group identifier as bytes.
This is useful to have a long term identifier for a group, backup-proof, and common to any device.

Request: GroupGetBytesIdentifierRequest

  • group_id (uint64)

Response: GroupGetBytesIdentifierResponse

  • identifier (bytes)

Error Codes:

  • NOT_FOUND: group not found.

  • UNAUTHENTICATED: client key is invalid.

GroupNewStandardGroup#

Create a new standard group.
In a standard group all members are administrators, everyone can edit group details and manage group members.

Request: GroupNewStandardGroupRequest

  • name (optional string)

  • description (optional string)

  • admin_contact_ids (repeated uint64)

Response: GroupNewStandardGroupResponse

Error Codes:

  • NOT_FOUND: contacts not found.

  • INVALID_ARGUMENT: at least one contact does not support group v2.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupNewControlledGroup#

Create a new controlled group.
In a controlled group Administrators are specifically designated and they can edit group details and manage group members.
Simple members cannot manage the group but they can post messages, attachments and reactions.

Request: GroupNewControlledGroupRequest

  • name (optional string)

  • description (optional string)

  • admin_contact_ids (repeated uint64)

  • contact_ids (repeated uint64)

Response: GroupNewControlledGroupResponse

Error Codes:

  • NOT_FOUND: contacts not found.

  • INVALID_ARGUMENT: a contact cannot be in admins and members at the same time / at least one contact does not support group v2.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupNewReadOnlyGroup#

Create a new read-only group.
In read only groups only group administrators can manage the group and post messages.
Other users can only react to messages.

Request: GroupNewReadOnlyGroupRequest

  • name (optional string)

  • description (optional string)

  • admin_contact_ids (repeated uint64)

  • contact_ids (repeated uint64)

Response: GroupNewReadOnlyGroupResponse

Error Codes:

  • NOT_FOUND: contacts not found.

  • INVALID_ARGUMENT: a contact cannot be in admins and members at the same time / at least one contact does not support group v2.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupNewAdvancedGroup#

Create a new advanced group.
An advanced group allows to manually assign permissions to all members.

Request: GroupNewAdvancedGroupRequest

Response: GroupNewAdvancedGroupResponse

Error Codes:

  • NOT_FOUND: contacts not found.

  • INVALID_ARGUMENT: a contact cannot be in admins and members at the same time / at least one contact does not support group v2.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupDisband#

Close a group, every member will leave the group and the discussion will be locked for everyone.
Only administrators are allowed to disband a group.

Request: GroupDisbandRequest

  • group_id (uint64)

Response: GroupDisbandResponse

Error Codes:

  • NOT_FOUND: group not found.

  • INVALID_ARGUMENT: impossible to disband a keycloak group.

  • PERMISSION_DENIED: you are not admin in this group.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupLeave#

Leave a group, the discussion will still exists for other group members.
Any group member can leave a group at any time, except if you are the last administrator in this group (a group must always have an administrator).

Request: GroupLeaveRequest

  • group_id (uint64)

Response: GroupLeaveResponse

Error Codes:

  • NOT_FOUND: group not found.

  • INVALID_ARGUMENT: impossible to disband a keycloak group / you cannot leave a group if you are the only group administrator.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupUpdate#

Update a group by modifying a Group object retrieved from groupList of groupGet.
Supported modifications:

  • Add a member: create a new GroupMember and add it to members field

  • Remove a member: remove associated GroupMember from members field

  • Remove a pending member: remove associated GroupPendingMember from pendingMembers field

  • Update (pending) member permissions: update permissions in permissions field in GroupMember or GroupPendingMember

  • Update group name: modify name field

  • Update group description: modify description field
    Every other modifications will be ignored. You must keep groupId field properly set.

Request: GroupUpdateRequest

Response: GroupUpdateResponse

Error Codes:

  • NOT_FOUND: group not found.

  • PERMISSION_DENIED: you are not admin in this group.

  • INVALID_ARGUMENT: the new group version has not been updated / new group member not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupSetPhoto#

Request (Stream): GroupSetPhotoRequest

Response: GroupSetPhotoResponse

GroupSetPhotoRequestMetadata

GroupSetPhoto
Set a new photo for a group.
The photo can be jpeg or png but will be converted to jpeg and resolution will be limited to 1080x1080.

Error codes:
NOT_FOUND: group not found.
PERMISSION_DENIED: you are not admin in this group.
UNAUTHENTICATED: client key is invalid.
INTERNAL

Fields:

  • group_id (uint64)

  • filename (string)

  • file_size (uint64)

GroupDownloadPhoto#

Download the group picture as bytes, or the generated image for this group.
Pictures are always jpeg files with a maximum of 1080x1080 resolution.

Request: GroupDownloadPhotoRequest

  • group_id (uint64)

Response: GroupDownloadPhotoResponse

  • photo (bytes)

Error Codes:

  • NOT_FOUND: group not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

GroupUnsetPhoto#

Unset the current group picture if there is one.

Request: GroupUnsetPhotoRequest

  • group_id (uint64)

Response: GroupUnsetPhotoResponse

Error Codes:

  • NOT_FOUND: group not found.

  • INVALID_ARGUMENT: group does not have a photo.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

Identity Command Service#

Info

Associated Datatype: Identity

IdentityGet#

Get your identity details.

Request: IdentityGetRequest

  • Empty payload.

Response: IdentityGetResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

IdentityGetBytesIdentifier#

Get your Olvid identity as bytes.
This is useful to have a long term identifier for an identity, backup-proof, and common to any device.

Request: IdentityGetBytesIdentifierRequest

  • Empty payload.

Response: IdentityGetBytesIdentifierResponse

  • identifier (bytes)

Error Codes:

  • NOT_FOUND: identity not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

IdentityUpdateDetails#

Update your Olvid identity details (first name, last name, company and position).
At least one field in first and last name must be non empty.
Your details will be visible by your contacts, and your display name is computed from these details.
Details for a keycloak managed identity cannot be updated.

Request: IdentityUpdateDetailsRequest

Response: IdentityUpdateDetailsResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: identity not found.

  • INVALID_ARGUMENT: at least one of first name and last name must be non empty / cannot update a keycloak managed identity.

  • UNAUTHENTICATED: client key is invalid.

IdentitySetPhoto#

Request (Stream): IdentitySetPhotoRequest

Response: IdentitySetPhotoResponse

  • Empty payload.

IdentitySetPhotoRequestMetadata

IdentitySetPhoto
Set a profile picture for your identity.
This picture will be visible by your contacts.
The photo can be jpeg or png but will be converted to jpeg and resolution will be limited to 1080x1080.

Error codes:
NOT_FOUND: identity not found.
UNAUTHENTICATED: client key is invalid.
INTERNAL

Fields:

  • filename (string)

  • file_size (uint64)

IdentityDownloadPhoto#

Download your current identity picture.
Pictures are always jpeg files with a maximum of 1080x1080 resolution.

Request: IdentityDownloadPhotoRequest

  • Empty payload.

Response: IdentityDownloadPhotoResponse

  • photo (bytes)

Error Codes:

  • NOT_FOUND: identity not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

IdentityRemovePhoto#

Remove your current identity picture.
The automatically generated identity image will be used instead.

Request: IdentityRemovePhotoRequest

  • Empty payload.

Response: IdentityRemovePhotoResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: identity not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

IdentityGetApiKeyStatus#

Check your current Olvid API key status.
API keys allow an identity to initiate calls or to use multi device.

Request: IdentityGetApiKeyStatusRequest

  • Empty payload.

Response: IdentityGetApiKeyStatusResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

IdentitySetApiKey#

Manually set an Olvid api key.
Olvid api keys are standard uuids.

Request: IdentitySetApiKeyRequest

  • api_key (string)

Response: IdentitySetApiKeyResponse

Error Codes:

  • INVALID_ARGUMENT: api key format is not valid.

  • UNAUTHENTICATED: client key is invalid.

Invitation Command Service#

Info

Associated Datatype: Invitation

InvitationList#

List invitations for current identity.
Pass a filter to select only invitations that match specific criteria.

Request: InvitationListRequest

Response (Stream): InvitationListResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

  • INVALID_ARGUMENT: invalid filter.

  • INTERNAL

InvitationGet#

Get invitation by id.

Request: InvitationGetRequest

  • invitation_id (uint64)

Response: InvitationGetResponse

Error Codes:

  • NOT_FOUND: invitation not found.

  • UNAUTHENTICATED: client key is invalid.

InvitationNew#

Send an invitation to another Olvid user using its invitation link.
Invitation links start with https://invitation.olvid.io#.
Sending an invitation will initiate an invitation protocol and create a new Invitation.

Request: InvitationNewRequest

  • invitation_url (string)

Response: InvitationNewResponse

Error Codes:

  • INVALID_ARGUMENT: you cannot invite yourself / invitation link is invalid.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

InvitationAccept#

Accept a pending invitation. This will allow protocol to continue.
This command is only possible if invitation.status is one of the following:

  • STATUS_INVITATION_WAIT_YOU_TO_ACCEPT

  • STATUS_INTRODUCTION_WAIT_YOU_TO_ACCEPT

  • STATUS_ONE_TO_ONE_INVITATION_WAIT_YOU_TO_ACCEPT

  • STATUS_GROUP_INVITATION_WAIT_YOU_TO_ACCEPT

Request: InvitationAcceptRequest

  • invitation_id (uint64)

Response: InvitationAcceptResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: invitation not found.

  • INVALID_ARGUMENT: cannot accept an invitation with this status.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

InvitationDecline#

Decline a pending invitation. This will abort protocol.
For invitation, introduction and one to one invitation the other user is not notified you declined the invitation.
This command is only possible if invitation.status is one of the following:

  • STATUS_INVITATION_WAIT_YOU_TO_ACCEPT

  • STATUS_INTRODUCTION_WAIT_YOU_TO_ACCEPT

  • STATUS_ONE_TO_ONE_INVITATION_WAIT_YOU_TO_ACCEPT

  • STATUS_GROUP_INVITATION_WAIT_YOU_TO_ACCEPT

Request: InvitationDeclineRequest

  • invitation_id (uint64)

Response: InvitationDeclineResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: invitation not found.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

InvitationSas#

Only possible if invitation.status is equal to STATUS_INVITATION_WAIT_YOU_FOR_SAS_EXCHANGE.
Set the 4 digit code shown on your partner device.

Request: InvitationSasRequest

  • invitation_id (uint64)

  • sas (string - 4 digit pin code shown on your partner device)

Response: InvitationSasResponse

  • Empty payload.

Error Codes:

  • NOT_FOUND: invitation not found.

  • INVALID_ARGUMENT: unexpected invitation status.

  • UNAUTHENTICATED: client key is invalid.

InvitationDelete#

Abort the protocol associated to any invitation and delete this invitation.

Request: InvitationDeleteRequest

  • invitation_id (uint64)

Response: InvitationDeleteResponse

  • Empty payload.

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

Settings Command Service#

Info

Associated Datatype: Settings

SettingsIdentityGet#

Get current settings for your identity.

Request: SettingsIdentityGetRequest

  • Empty payload.

Response: SettingsIdentityGetResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid.

SettingsIdentitySet#

Update your identity settings.
⚠️ Update erases the WHOLE settings.
To update current settings use SettingsIdentityGet to get current config, and only edit fields you want to update.

Request: SettingsIdentitySetRequest

Response: SettingsIdentitySetResponse

Error Codes:

  • INVALID_ARGUMENT: cannot set keycloak settings if your identity is not keycloak managed.

  • UNAUTHENTICATED: client key is invalid.

SettingsDiscussionGet#

Get a discussion settings.
Those settings are shared with other members of this discussion.
For example, a parameter for ephemeral message parameters concerning a discussion would affect all future messages posted in this discussion, from any member.

Request: SettingsDiscussionGetRequest

  • discussion_id (uint64)

Response: SettingsDiscussionGetResponse

Error Codes:

  • NOT_FOUND: discussion not found

  • UNAUTHENTICATED: client key is invalid.

SettingsDiscussionSet#

Update a discussion settings.
⚠️ Update erases the WHOLE settings.
To update current settings use SettingsDiscussionGet to get current config, and only edit fields you want to update.

Request: SettingsDiscussionSetRequest

Response: SettingsDiscussionSetResponse

Error Codes:

  • NOT_FOUND: discussion not found

  • UNAUTHENTICATED: client key is invalid.

Storage Command Service#

Info

Each client key has its own independent storage space, with a simple key-value system.
Storage can be seen as a global storage space, compared to Discussion Storage that offers a space associated with a specific discussion.

Both mechanisms are backup resilient, and will be restored with their associated client key in a backup restoration process.

Mind that temporary client keys (specified in daemon environment or as command line arguments) do not have an allocated storage space.
You must create a client in database to use storage commands.

Associated Datatype: Storage

StorageList#

List stored elements in global storage scope, for current client key.
Pass a filter to select only elements that match specific criteria.

Mind that temporary client keys (specified in daemon environment or as command line arguments) does not have an allocated storage space.
You must create a client in database to use storage commands.

Request: StorageListRequest

Response (Stream): StorageListResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

  • INVALID_ARGUMENT: invalid filter

  • INTERNAL

StorageGet#

Request the value associated to a key in your global storage.
If the key does not already exist, return an empty string.

Request: StorageGetRequest

  • key (string)

Response: StorageGetResponse

  • value (string)

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

StorageSet#

Set the value for a key in your global storage.
If the key was already set the value is updated and it returns the previous_value in response.

Request: StorageSetRequest

  • key (string)

  • value (string)

Response: StorageSetResponse

  • previous_value (string - if the key already exists, this contains the erased value.)

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

  • INTERNAL

StorageUnset#

Unset a key in your global storage.

Request: StorageUnsetRequest

  • key (string)

Response: StorageUnsetResponse

  • previous_value (string - the value previously associated to this key)

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

Discussion Storage Command Service#

Info

Each client key has its own independent storage space, with a simple key-value system.
Storage can be seen as a global storage space, compared to Discussion Storage that offers a space associated with a specific discussion.

Both mechanisms are backup resilient, and will be restored with their associated client key in a backup restoration process.

Mind that temporary client keys (specified in daemon environment or as command line arguments) do not have an allocated storage space.
You must create a client in database to use storage commands.

Associated Datatype: Storage

DiscussionStorageList#

List stored elements in a specific discussion storage scope, for current client key.
Pass a filter to select only elements that match specific criteria.

Request: DiscussionStorageListRequest

Response (Stream): DiscussionStorageListResponse

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

  • INVALID_ARGUMENT: discussion storage is not available with an admin client key / invalid filter.

  • NOT_FOUND: discussion not found.

  • INTERNAL

DiscussionStorageGet#

Request the value associated to a key in the specified discussion storage.
If the key does not already exist, return an empty string.

Request: DiscussionStorageGetRequest

  • discussion_id (uint64)

  • key (string)

Response: DiscussionStorageGetResponse

  • value (string)

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

  • INVALID_ARGUMENT: discussion storage is not available with an admin client key.

  • NOT_FOUND: discussion not found.

DiscussionStorageSet#

Set the value for a key in the specified discussion storage.
If the key was already set the value is updated and it returns the previous_value in response.

Request: DiscussionStorageSetRequest

  • discussion_id (uint64)

  • key (string)

  • value (string)

Response: DiscussionStorageSetResponse

  • previous_value (string)

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

  • INVALID_ARGUMENT: discussion storage is not available with an admin client key.

  • NOT_FOUND: discussion not found.

  • INTERNAL

DiscussionStorageUnset#

Unset a key in the specified discussion storage.

Request: DiscussionStorageUnsetRequest

  • discussion_id (uint64)

  • key (string)

Response: DiscussionStorageUnsetResponse

  • previous_value (string)

Error Codes:

  • UNAUTHENTICATED: client key is invalid or a temporary client key.

  • INVALID_ARGUMENT: discussion storage is not available with an admin client key.

  • NOT_FOUND: discussion not found.

Keycloak Command Service#

Info

Associated Datatype: Keycloak

KeycloakBindIdentity#

Register your identity in a keycloak directory.
Your identity should not already be registered in a keycloak directory (identity.keycloak_managed).
When registered your directory might add you to some managed groups, and you will be granted access to other directory users.
Other directory users can be added as contacts with no further confirmation (see KeycloakUserList and KeycloakAddUserAsContact).

Request: KeycloakBindIdentityRequest

  • configuration_link (string)

Response: KeycloakBindIdentityResponse

  • Empty payload.

Error Codes:

  • INVALID_ARGUMENT: identity is already keycloak managed.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

KeycloakUnbindIdentity#

Unregister from a keycloak directory.
Your identity should already be keycloak managed.
You will lose access to keycloak user directory and you will leave keycloak managed groups.
Your keycloak managed contacts will remain contacts but won’t be keycloak managed anymore.

Request: KeycloakUnbindIdentityRequest

  • Empty payload.

Response: KeycloakUnbindIdentityResponse

  • Empty payload.

Error Codes:

  • INVALID_ARGUMENT: identity is not keycloak managed.

  • UNAUTHENTICATED: client key is invalid.

KeycloakUserList#

List other users registered on your keycloak directory.
Pass a filter to select only users that match specific criteria.

Request: KeycloakUserListRequest

  • filter (optional KeycloakUserFilter)

  • last_list_timestamp (optional uint64 - only users that registered on keycloak since this timestamp, set to 0 to list all users.)

Response (Stream): KeycloakUserListResponse

  • users (repeated KeycloakUser)

  • last_list_timestamp (uint64 - set this timestamp in request.last_list_timestamp if you want to list only new users.)

Error Codes:

  • INVALID_ARGUMENT: identity is not keycloak managed / invalid filter.

  • UNAUTHENTICATED: client key is invalid.

  • INTERNAL

KeycloakAddUserAsContact#

Add a user from keycloak directory as a contact.
This will not trigger any invitation protocol.
Directory is considered as a trusted third party so no further confirmation is required.
Contact and discussion will be created as soon as one of the other user’s device is online and automatically answer “invitation”.

Request: KeycloakAddUserAsContactRequest

  • keycloak_id (string)

Response: KeycloakAddUserAsContactResponse

  • Empty payload.

Error Codes:

  • INVALID_ARGUMENT: identity is not keycloak managed.

  • NOT_FOUND: keycloak user not found.

  • UNAUTHENTICATED: client key is invalid.

Call Command Service#

Info

Currently daemon cannot handle Olvid calls properly.
You can be notified on incoming calls, and you can initiate call within discussions or with any contact.
But we cannot manage audio or video streams, that’s why a daemon will always answer any incoming call with a “busy” response.

Associated Datatype: Call

CallStartDiscussionCall#

Start a call with one discussion member(s).
This will start a one to one call or a group call depending on discussion type.
You can use call_identifier to filter later call notifications.

Request: CallStartDiscussionCallRequest

  • discussion_id (uint64)

Response: CallStartDiscussionCallResponse

  • call_identifier (string)

Error Codes:

  • NOT_FOUND: discussion not found.

  • INVALID_ARGUMENT: cannot start a call in an empty group.

  • INTERNAL

  • UNAUTHENTICATED: client key is invalid.

CallStartCustomCall#

Start a call with any contacts, even if they do not belong to the same discussion.
You can use call_identifier to filter later call notifications.

Request: CallStartCustomCallRequest

  • contact_ids (repeated uint64)

  • discussion_id (optional uint64 - specify in which discussion other contacts will log call)

Response: CallStartCustomCallResponse

  • call_identifier (string)

Error Codes:

  • NOT_FOUND: discussion or contact not found.

  • UNAUTHENTICATED: client key is invalid.

Tool Command Service#

Info

A set of utility entrypoint to test debug and your configuration.

Ping#

Unauthenticated method.
Just check if daemon is reachable.

Request: PingRequest

  • Empty payload.

Response: PingResponse

  • Empty payload.

DaemonVersion#

Authenticated method.
Ask daemon its version.

Request: DaemonVersionRequest

  • Empty payload.

Response: DaemonVersionResponse

  • version (string)

AuthenticationTest#

Authenticated rpc.
Check that sent credentials are valid user credentials, else it returns an error.

Request: AuthenticationTestRequest

  • Empty payload.

Response: AuthenticationTestResponse

  • Empty payload.

Error Codes:

  • PERMISSION_DENIED: invalid client key.

AuthenticationAdminTest#

Authenticated rpc (admin key only).
Check that sent credentials are valid admin credentials, else it returns an error.

Request: AuthenticationAdminTestRequest

  • Empty payload.

Response: AuthenticationAdminTestResponse

  • Empty payload.

Error Codes:

  • PERMISSION_DENIED: client key is not an admin client key.

Contents