API docs by Redocly

SVX API (1.4.2)

Download OpenAPI specification:Download

Organisations

Create application agent

Create application agent

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-Id
required
string <uuid>
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "application": {
    }
}

Response samples

Content type
application/json
{
  • "application": {
    }
}

Load all application agents

Load all application agents

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-Id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ]
}

Get application agent information

Get application agent information

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-Id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "application": {
    }
}

Update application agent

Update application agent

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-Id
required
string <uuid>
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "application": {
    }
}

Response samples

Content type
application/json
{
  • "application": {
    }
}

Delete application agent

Delete application agent

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-Id
required
string <uuid>

Responses

Delete an organisation

Delete an organisation.

In order to execute this action the current user must have security right atom:tenant:create_org for the tenant of the organisation.

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

View an organisation

Show an organisation.

In order to execute this action the current user must have

  • global security atom:global:view_all_orgs or
  • security right atom:tenant:view_tenant_orgs for the tenant
  • security right atom:org:view_org for the org with the ID in parameter org_id
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

Responses

Response samples

Content type
application/json
{
  • "org": {
    }
}

Update an organisation

Update an organisation.

In order to execute this action the current user must have security right atom:tenant:create_org for the tenant with the ID in parameter tenant_id.

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

Request Body schema: application/json

Organisation attributes

authorised_officer_email
string

Authorised officer email

authorised_officer_first_name
string

Authorised officer first name

authorised_officer_last_name
string

Authorised officer last name

business_address
string

Business address

color
string

The color associated with the organisation in the hex format. Used for the UI.

company_number
string

Company number

company_url
string or null <uri>

URL of the company

legal_name
string

Legal number

lei_number
string

Legal entity identification number

logo_url
string <uri>

URL to a logo image

name
required
string

Name of the organisation to create

status_in_tenant
string

Status: signed legal agreement received or proof of concept

trading_name
string

Trading number

Responses

Request samples

Content type
application/json
{
  • "authorised_officer_email": "string",
  • "authorised_officer_first_name": "string",
  • "authorised_officer_last_name": "string",
  • "business_address": "string",
  • "color": "string",
  • "company_number": "string",
  • "company_url": "http://example.com",
  • "legal_name": "string",
  • "lei_number": "string",
  • "logo_url": "http://example.com",
  • "name": "string",
  • "status_in_tenant": "string",
  • "trading_name": "string"
}

Response samples

Content type
application/json
{
  • "org": {
    }
}

List admins of an organisation

List admins of an organisation.

It is also possible to request a list of archived admins of the organisation, that is, users who used to have organisation security rights for the given organisation, but do not have them now.

In order to execute this action the current user must have

  • security right atom:org:list_org_admins for the organisation with the ID in parameter org_id or
  • security right atom:tenant:list_admins_of_all_orgs_of_tenant for the parent tenant of the organisation org_id or
  • global security right `atom:global:list_admins_of_all_orgs
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

query Parameters
status
string
Enum: "active" "archived"

admin status: active, or archived

email
string

search admins by their email address. Currenty works only with status=archived

per_page
integer

number of admins per page

page
integer

Number of the page to serve. This parameter activates classic page-based pagination and cannot be used with parameter next_page_after which activates cursor-based pagination.

order
string
Enum: "asc" "desc"

order admins by given name in ascending or descending order

next_page_after
string

When cursor based pagination is used, each paginated response has value next_page_after which, if submitted as a parameter, allows to retrieve the next page. next_page_after is null is there is no next page. next_page_after cannot be used together with parameter page. page activates classic page-based pagination.

Responses

Response samples

Content type
application/json
{
  • "admins": [
    ],
  • "meta": { },
  • "next_page_after": "string"
}

Remove all organisation security rights from user

Remove all organisation security rights from user.

In order to execute this action the current user must one of the following security rights:

  • atom:global:assign_org_sr_to_user
  • atom:tenant:assign_org_sr_to_user
  • atom:org:assign_org_sr_to_user
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

org_admin_id
required
string <uuid>

ID of the admin

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

Show an admin of a given organisation

Show an admin of a given organisation.

In order to execute this action the current user must have

  • security right atom:org:list_org_admins for the organisation with the ID in parameter org_id or
  • security right atom:tenant:list_admins_of_all_orgs_of_tenant for the parent tenant of the organisation org_id or
  • global security right `atom:global:list_admins_of_all_orgs
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

org_admin_id
required
string <uuid>

ID of the admin

Responses

Response samples

Content type
application/json
{
  • "admin": {
    }
}

Archive an organisation admin

Remove a user from admins of the given organisation, and put the admin into the registry of former admins of that organisation.

In order to execute this action the current user must one of the following security rights:

  • atom:global:assign_org_sr_to_user
  • atom:tenant:assign_org_sr_to_user
  • atom:org:assign_org_sr_to_user
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

org_admin_id
required
string <uuid>

ID of the admin

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

Restore an archived organisation admin

Reinstate an archived user and make him/her a org admin again.

In order to execute this action the current user must one of the following security rights:

  • atom:org:assign_org_sr_to_user
  • atom:tenant:assign_org_sr_to_user
  • atom:global:assign_org_sr_to_user
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

org_admin_id
required
string <uuid>

ID of the admin

Responses

Response samples

Content type
application/json
{
  • "admin": {
    }
}

List security rights of an organisation admin

List organisation security rights of a organisation admin.

In order to execute this action the current user must have security right atom:org:list_org_admin_sr for the organisation with the ID in parameter org_id or atom:tenant:list_org_admin_sr for the tenant that the organisation belongs to, or global security right atom:global:list_admin_sr_of_any_admin"

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

org_admin_id
required
string <uuid>

ID of an organisation admin

Responses

Response samples

Content type
application/json
{
  • "security_rights": [
    ]
}

Assign organisation security rights to a user

Assign organisation security rights to a user.

The endpoint can process security rights of 2 categories:

  • for_org = true and for_tenant = false
  • for_org = true and for_tenant = true, in this case the security right will be assigned to the tenant which organisation belongs to

In order to execute this action the current user must have one of the following security rights:

  • security right atom:org:assign_org_sr_to_user for the organisation with the ID in parameter org_id
  • security right atom:tenant:assign_org_sr_to_user for the tenant that the organisation belongs to
  • global security right atom:global:assign_org_sr_to_user"
Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

org_admin_id
required
string <uuid>

ID of an organisation admin

Request Body schema: application/json

list of security rights

security_rights
required
Array of strings

list of security rights

Responses

Request samples

Content type
application/json
{
  • "security_rights": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

Archive an organisation

Archive an organisation.

In order to execute this action the current user must have security right atom:tenant:create_org for the tenant of the organisation.

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

Responses

Response samples

Content type
application/json
{
  • "org": {
    }
}

Restore an organisation

Restore an organisation.

In order to execute this action the current user must have security right atom:tenant:create_org for the tenant of the organisation.

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

Responses

Response samples

Content type
application/json
{
  • "org": {
    }
}

Add security rights to an organisation

Add security rights to an organisation.

In order to execute this action the current user must have security right atom:tenant:assign_sr_to_org for the tenant which the organisation belongs to.

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

Request Body schema: application/json

list of security rights

security_rights
required
Array of strings

list of security rights

Responses

Request samples

Content type
application/json
{
  • "security_rights": [
    ]
}

Response samples

Content type
application/json
{
  • "org": {
    }
}

Remove security rights from an organisation

Remove security rights from an organisation.

In order to execute this action the current user must have security right atom:tenant:assign_sr_to_org for the tenant which the organisation belongs to.

Authorizations:
SVX-JWT
path Parameters
org_id
required
string <uuid>

ID of the organisation

security_rights
required
string

Comma-separated security rights to remove

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

List organisation in a tenant

List organisations in a tenant.

In order to execute this action the current user must have global security atom:global:view_all_orgs or security right atom:tenant:view_tenant_orgs for the tenant with the ID in parameter tenant_id.

Authorizations:
SVX-JWT
path Parameters
tenant_id
required
string <uuid>

ID of the tenant

query Parameters
status
string
Enum: "active" "archived" "all"

org status: active, archived, or all

per_page
integer

number of organisations per page

order
string
Enum: "asc" "desc"

order organisations by name in ascending or descending order

page
integer

Number of the page to serve. This parameter activates classic page-based pagination and cannot be used with parameter next_page_after which activates cursor-based pagination.

next_page_after
string

When cursor based pagination is used, each paginated response has value next_page_after which, if submitted as a parameter, allows to retrieve the next page. next_page_after is null is there is no next page. next_page_after cannot be used together with parameter page. page activates classic page-based pagination.

filter_by
string

Search organisations whose names contains the given string.

Responses

Response samples

Content type
application/json
{
  • "meta": { },
  • "next_page_after": "string",
  • "orgs": [
    ]
}

Create an organisation

Create an organisation.

In order to execute this action the current user must have security right atom:tenant:create_org for the tenant with the ID in parameter tenant_id.

Authorizations:
SVX-JWT
path Parameters
tenant_id
required
string <uuid>

ID of the tenant

query Parameters
no_first_user
boolean

If true, the current user will not become the first admin of the organisation, and the organisation will have not admins. By default the current user becomes the first admin of the organisation

add_all_external_security_rights
boolean

By default only all internal org-level security rights of the parent tenant are added to a new organisation If this parameter is true, also all external org-level security rights of the parent tenant are added to a new organisation.

Request Body schema: application/json

Organisation attributes

authorised_officer_email
string

Authorised officer email

authorised_officer_first_name
string

Authorised officer first name

authorised_officer_last_name
string

Authorised officer last name

business_address
string

Business address

color
string

The color associated with the organisation in the hex format. Used for the UI.

company_number
string

Company number

company_url
string or null <uri>

URL of the company

legal_name
string

Legal number

lei_number
string

Legal entity identification number

logo_url
string <uri>

URL to a logo image

name
required
string

Name of the organisation to create

status_in_tenant
string

Status: signed legal agreement received or proof of concept

trading_name
string

Trading number

Responses

Request samples

Content type
application/json
{
  • "authorised_officer_email": "string",
  • "authorised_officer_first_name": "string",
  • "authorised_officer_last_name": "string",
  • "business_address": "string",
  • "color": "string",
  • "company_number": "string",
  • "company_url": "http://example.com",
  • "legal_name": "string",
  • "lei_number": "string",
  • "logo_url": "http://example.com",
  • "name": "string",
  • "status_in_tenant": "string",
  • "trading_name": "string"
}

Response samples

Content type
application/json
{
  • "org": {
    }
}

Show a list of organisations which current user can see.

Show a list of organisations which the current user can see. These are the following organisations:

  • If the current user has global security right atom:global:view_all_tenants, all organisations are shown
  • Organisations of all tenants for which the current user has tenant security right atom:tenant:view_tenant_orgs
  • Organisations for which current user is an admin and has security right atom:org:view_org

Can take optional parameter tenant_id which will restrict the list of organisations to one tenant only.

Authorizations:
SVX-JWT
query Parameters
tenant_id
string <uuid>

This parameter is the ID of a tenant and if present it restricts the list of organisations to one tenant only.

Responses

Response samples

Content type
application/json
{
  • "orgs": [
    ]
}

Classifications

Returns a list of classification nodes

Fetches classification nodes.

There are 2 types of classification nodes:

  • global classification nodes
  • classification nodes created by the current user

This endpoint serves both global and your own classication nodes. Field own specifies which kind of classigication node this is

You can fetch classification nodes belonging to a certain classification scheme. You can also filter classification nodes by a LIKE expression on the name.

Parameter own allows you to request only global or only user-defined classification nodes.

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

scheme_name
string

Filter classification nodes by the name of the classification scheme

name
string

this is a 'LIKE' search intended for use in searching for classification nodes, mostly tags. For example adding 'trav' might return a classification node with the name 'travel'

own
string

If the value is 'true', only user-defined classification nodes are returned, if the value is 'false', only global classification nodes are returned.

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "classification_nodes": [
    ],
  • "meta": {
    }
}

Create a new classification node in a user-owned scheme

There are 2 types of classification schemes:

  • owned by users - each user can create their own classification nodes
  • global - nodes are created by the system

This endpoint allows a user to create a new classification node in a user-owned classification scheme.

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "classification_node": {
    }
}

Response samples

Content type
application/json
{
  • "classification_node": {
    }
}

Shows a classification node

Retrieve a classification node

Authorizations:
SVX-JWT
path Parameters
id
required
string

Classification Node id

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "classification_node": {
    }
}

Connections

Get connections

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

page
integer

specify page number in page-based pagination. The default pagination mode is cursor-based pagination, in order to swtich to page-based pagination this parameter must ne used, even for the first page

delegation
string

Request connection where the current user has granted delegation to other users (granted_to_the_other_user) or where the current user has received delegation from other users (granted_to_me). The list of connections is ordered by created_at in the descending order.

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "connections": [
    ],
  • "meta": {
    },
  • "next_page_after": "string"
}

Create Connection

Accepts an invitation and creates 2 connection records: a connection from the current user to the user who invited the current user, and a connection from the user who invited the current user to the current user.

If there were share intents linked to this invitation, shares are created. The response contains a report on the created shares. This endpoint is only available when global configuration variable multistep_invitation_workflow is false

If there is already a connection between these two users, then

  • the response will contain the existing connection
  • field invitation will be set to NULL
  • field connection_existed_already will be set to true
  • any share intents attached to the invitation will be used to create shares
Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
object (PostConnectionPublicKey)
object (PostConnection)

Responses

Request samples

Content type
application/json
{
  • "public_key": {
    },
  • "connection": {
    }
}

Response samples

Content type
application/json
{
  • "connection_existed_already": true,
  • "connection": {
    },
  • "created_shares_report": [
    ]
}

Delete Connection

Deletes a connection.

A backend to backend call to the keystore will automatically delete the corresponding keystore delegation if applicable.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Get Connection

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "connection": {
    }
}

List invitations

Retrieves invitations that the current user has created. Parameter state fetches invitations with a certain state. Currenty there are 6 states:

  • new
  • connected
  • rejected
  • accepted
  • cancelled
  • expired

If parameter state is not submitted, only invitations with states new, accepted and rejected are fetched.

Authorizations:
SVX-JWT
query Parameters
state
string

only fetch invitations with a certain state. Currenty there are 5 states: new, connected, accepted, rejected, cancelled, expired.

next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

page
integer

specify page number in page-based pagination. The default pagination mode is cursor-based pagination, in order to swtich to page-based pagination this parameter must ne used, even for the first page

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "invitations": [
    ],
  • "meta": {
    }
}

Create an invitation

Invite another user to connect.

An invitation does not specify a recipient directly, instead the result of this operation is an invitation token which can then be sent to a recipient by a client application or some other means, mand the recipient can create a connection using this token and endpoint POST /connections

Invitations and connections have 3 special use-cases:

  1. a connection between an organization agent and an organization member
  2. a connection between a service agent and a user of the service
  3. a connection between a user and a delegate user who has been granted permissions to act on behalf of the user

Blindly accepting an invitation by submitting an invitation token to POST /connections might have serious consequences, so client applications are advised to first read the invitation with GET /invitations/{token}before creating a connection. The intent of an invitation is in JSON field integration_data.

For the membership invitation parameter organization_member_role is used to specify the role we are inviting the user with. There are currently 2 organization member roles:

  • owner - can do everything
  • admin (default) - can only manage organization services If param organization_member_role is not provided then role admin will be assigned to the invited member.

For the delegation connection parameters delegate_role and delegation_token are mandatory. delegation_token should be obtained by running POST /delegations in the keystore.

If delegate_role and delegation_token are present, a recipient is invited to become a delegate user who has rights to perform actions on behalf of the user who has created the invitation.

Currently there are three delegate roles:

  • owner
  • admin
  • reader

The vault supports two invitations workflows:

  • Simple - a sender creates an invitation. A recipient then accepts the invitation, and a connection is created.

  • Multistep - a sender creates an invitation. A recipient then accepts the invitation, no connection is created yet. The recipient then confirms the invitation, and a connection is created.

An invitation is marked as belonging to one of these two workflows when created, boolean parameter multistep_workflow can be used for this. Values '1' and 'true' are interpreted as true, as multistep invitation workflow.

Each vault instance is configured to have a default invitation workflow. In case multistep_workflow is not submitted or is null, the default workflow is used.

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
expires_in
integer or null

number of days the invitation is valid. Cannot exceed the default value

object (PostInvitationPublicKey)
object (PostInvitation)

Responses

Request samples

Content type
application/json
{
  • "expires_in": 0,
  • "public_key": {
    },
  • "invitation": {
    }
}

Response samples

Content type
application/json
{
  • "invitation": {
    }
}

Delete an invitation

Delete an invitation by its token or ID. Only the user who created the invitation may delete it.

Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

invitation ID or token

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Read an invitation

Read an invitation by its token or ID.

Can be used by both the invitation sender, and someone with an invitation token.Fields id and keypair_external_id are NULL if the current user is not the sender of the invitation

Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

invitation ID or token

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "invitation": {
    },
  • "share_intents": [
    ],
  • "recipient_public_key": "string"
}

Accept an invitation

Accept an invitation.

This endpoint is only available if the multistep invitation flow is enabled. Accepting an endpoint does not create a connection. After an invitation is accepted, the sender of the invitation needs to confirm it.

If there is already a connection between these two users, then

  • the response will contain the existing connection
  • field invitation will be set to NULL
  • field connection_existed_already will be set to true
  • any share intents attached to the invitation will be used to create shares
Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

invitation token

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
object (AcceptInvitationPublicKey)
object (AcceptInvitationParams)

Responses

Request samples

Content type
application/json
{
  • "public_key": {
    },
  • "invitation": {
    }
}

Response samples

Content type
application/json
{
  • "connection_existed_already": true,
  • "invitation": {
    },
  • "connection": {
    }
}

Reject an accepted invitation

Reject an accepted invitation.

This endpoint is only available if the multistep invitation flow is enabled. First an invitation recipient accepts an an invitation is accepted, and then the sender of the invitation can reject it using this endpoint. Only the sender of the invitation can call this endpoint.

Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

invitation ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "invitation": {
    }
}

Confirm an accepted invitation

Confirm an accepted invitation.

This endpoint is only available if the multistep invitation flow is enabled. First an invitation recipient accepts an an invitation is accepted, and then the sender of the invitation can confirm it using this endpoint. Only the sender of the invitation can call this endpoint.Parameter encrypted_dek is used for share intents in the multistep invitation workflow. In the multistep invitation workflow when share intents are created, they are first encrypted with the private DEK on the invitation sender. At this confirmation step the sender of the invitation already has access to the public key of the recipient in the invitation, field recipient_public_key, and the sender of the invitation is expected to re-encrypt the DEK in the share intents with the public key of the recipient. encrypted_dek is mandatory if there are share intents.

If there is already a connection between these two users, then

  • the response will contain the existing connection
  • field invitation will be set to NULL
  • field connection_existed_already will be set to true
  • any share intents attached to the invitation will be used to create shares
Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

invitation ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
encrypted_recipient_name
string

Name of the recipient of the invitation re-encrypted with the private DEK of the sender of the invitation

encrypted_dek
string

This parameter is used for share intents in the multistep invitation workflow. In the multistep invitation workflow when share intents are created, they are first encrypted with the private DEK on the invitation sender. At this confirmation step the sender of the invitation already has access to the public key of the recipient in the invitation, field recipient_public_key, and the sender of the invitation is expected to re-encrypt the DEK in the share intents with the public key of the recipient. encrypted_dek is mandatory if there are share intents.

Responses

Request samples

Content type
application/json
{
  • "encrypted_recipient_name": "string",
  • "encrypted_dek": "string"
}

Response samples

Content type
application/json
{
  • "connection_existed_already": true,
  • "invitation": {
    },
  • "connection": {
    }
}

Reject an invitation

Reject an invitation. This endpoint is only available if the multistep invitation flow is enabled.

Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

invitation token

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "invitation": {
    }
}

Delegations

Create a child user

In delegation we differentiate between a delegate user and an owner user:

  • owner - a user who grants delegation permissions, the real owner of the account
  • delegate - a user who has been granted permission to perform actions on the behalf of the owner

One way to set up a delegation relation is via invitations. Any user can invite another user to become a delegate. See POST /invitations for details.

Another way is creating a child user. A child account is a new empty account over which the user who has created it has full control via a delegation connection with role owner.

The user who has created a child account is considered a parent account. Managing keys of the child account the responsibility of the parent user.

The result of this call is a child account without a private DEK but with a login public key.

In order to create a child account the following data must be submitted:

  • Public key and the corresponding keypair external ID of the current user (parent) to create the connection
  • Public key and the corresponding keypair external ID of the child user (parent) to create the connection
  • Login public key for the child account.
Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json

Parameters to create a child account and a connection between the parent user and the child user

object (ParentPublicKeyForConnection)
object (ChildPublicKeyForConnection)

Responses

Request samples

Content type
application/json
{
  • "parent_public_key_for_connection": {
    },
  • "child_public_key_for_connection": {
    }
}

Response samples

Content type
application/json
{
  • "user": {
    },
  • "connection_from_parent_to_child": {
    }
}

Create a delegation invitation

Invite an existing connection to become a delegate of your account. They will have rights to perform actions on behalf of the user who has created the invitation.

There are three delegation roles:

  • owner
  • admin
  • reader

delegation_token should be obtained by running POST /delegations in the keystore.

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
connection_id
string <uuid>
delegation_token
string
delegation_role
string

Responses

Request samples

Content type
application/json
{
  • "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9",
  • "delegation_token": "string",
  • "delegation_role": "string"
}

Response samples

Content type
application/json
{
  • "delegation_invitation": {
    }
}

List incoming invitations

Retrieves invitations that the current user has created.

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "delegation_invitations": [
    ],
  • "meta": {
    }
}

List outgoing invitations

Retrieves invitations that have been sent to the current user.

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "delegation_invitations": [
    ],
  • "meta": {
    }
}

Delete a delegation invitation

Delete a delegation invitation by its ID. Users may only delete delegation invitations in the new state that they have created.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Read a delegation invitation

Read a delegation invitation by its ID. Both creator and recipient can read the invitation

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "delegation_invitation": {
    }
}

Accept a delegation invitation

Accept a delegation invitation by its ID and update the connection between the two users. Users may only accept delegation invitations in the new state that have been sent to them.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "connection": {
    }
}

Reject a delegation invitation

Reject a delegation invitation by its ID. Users may only reject delegation invitations in the new state that have been sent to them.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Removes configured delegation from a connection

Remove delegation from a connection

A backend to backend call to the keystore will automatically delete the corresponding keystore delegation.

Authorizations:
SVX-JWT
path Parameters
connection_id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Update a delegation

Update a delegation by its connection ID

Authorizations:
SVX-JWT
path Parameters
connection_id
required
string
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
delegation_role
string

Responses

Request samples

Content type
application/json
{
  • "delegation_role": "string"
}

Response samples

Content type
application/json
{
  • "connection": {
    }
}

DIDs

Get a list of registered organisation/user DIDs

This endpoint gets registered DID's own by organisation/user.

Authorizations:
SVX-JWT
query Parameters
limit
any
Example: limit=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
string

Get list of organisation own DIDs by providing Organisation Id

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "meta": {
    },
  • "links": {
    }
}

Create a DID Document

This endpoint creates a DID. As input it takes the DID, a DID document, plus optional DID registration options and secrets needed to create a DID. The output is a state object that represents the current state of the DID creation process.

See the DID Create Guide for detail usage of this endpoint.

Authorizations:
SVX-JWT
query Parameters
method
required
string
Examples:
  • method=key - key
  • method=web - web
  • method=indy - indy

The DID Method to create.

header Parameters
Meeco-Organisation-ID
string

Create DID for organisation by providing Organisation Id

Request Body schema: application/json
jobId
string
Default: null
object

This input field contains an object with various options for the DID create operation, such as the network where the DID should be created. See https://identity.foundation/did-registration/#options

secret
object

This input field contains an object with DID controller keys and other secrets needed for performing the DID create operation. See https://identity.foundation/did-registration/#secret

object

This input field contains either a complete DID document, or an incremental change (diff) to a DID document. See https://identity.foundation/did-registration/#diddocument

Responses

Request samples

Content type
application/json
{
  • "jobId": null,
  • "options": {
    },
  • "secret": { },
  • "didDocument": {
    }
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "didState": {
    },
  • "didRegistrationMetadata": {
    },
  • "didDocumentMetadata": {
    }
}

Deactivate a DID

This endpoint deactivates a DID. As input it takes the existing DID, plus optional DID registration options and secrets needed to deactivate a DID. The output is a state object that represents the current state of the DID deactivation process.

See the DID Deactivate Guide for detail usage of this endpoint.

Authorizations:
SVX-JWT
query Parameters
method
required
string
Examples:
  • method=web - web
  • method=indy - indy

The DID Method to create.

header Parameters
Meeco-Organisation-ID
string

Deactivate organisation DID by providing Organisation Id

Request Body schema: application/json
jobId
string
Default: null
did
required
string
object

This input field contains an object with various options for the DID create operation, such as the network where the DID should be created. See https://identity.foundation/did-registration/#options

secret
object

This input field contains an object with DID controller keys and other secrets needed for performing the DID create operation. See https://identity.foundation/did-registration/#secret

object

This input field contains either a complete DID document, or an incremental change (diff) to a DID document. See https://identity.foundation/did-registration/#diddocument

Responses

Request samples

Content type
application/json
{
  • "jobId": null,
  • "did": "string",
  • "options": {
    },
  • "secret": { },
  • "didDocument": {
    }
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "didState": {
    },
  • "didRegistrationMetadata": {
    },
  • "didDocumentMetadata": {
    }
}

Update a DID

This endpoint updates a DID. As input it takes the existing DID, a DID document, plus optional DID registration options and secrets needed to update a DID. The output is a state object that represents the current state of the DID update process.

See the DID Update Guide for detail usage of this endpoint.

Authorizations:
SVX-JWT
query Parameters
method
required
string
Examples:
  • method=web - web
  • method=indy - indy

The DID Method to create.

header Parameters
Meeco-Organisation-ID
string

Update organisation DID by providing Organisation Id

Request Body schema: application/json
jobId
string
Default: null
did
required
string
didDocumentOperation
required
Array of strings
object

This input field contains an object with various options for the DID create operation, such as the network where the DID should be created. See https://identity.foundation/did-registration/#options

secret
object

This input field contains an object with DID controller keys and other secrets needed for performing the DID create operation. See https://identity.foundation/did-registration/#secret

object

This input field contains either a complete DID document, or an incremental change (diff) to a DID document. See https://identity.foundation/did-registration/#diddocument

Responses

Request samples

Content type
application/json
{
  • "jobId": null,
  • "did": "string",
  • "didDocumentOperation": [
    ],
  • "options": {
    },
  • "secret": { },
  • "didDocument": {
    }
}

Response samples

Content type
application/json
{
  • "jobId": "string",
  • "didState": {
    },
  • "didRegistrationMetadata": {
    },
  • "didDocumentMetadata": {
    }
}

Resolve a DID

This endpoint resolves a DID. As input it takes the DID, plus DID resolution options. The output is a DID document in one of the supported representations, plus metadata. The same endpoint can also be used to dereference a DID URL. In this case, the output is a DID document, or part of a DID document, or some other resource identified by the DID URL.

See the DID Resolution specification for additional details.

Authorizations:
SVX-JWT
path Parameters
identifier
required
string
Examples:
  • did:key:z6MkuS4gudyuiFp5MGTsFfPSyn4uUQKhY8vFFzPMNQDANoLd - key
  • did:web:did-web.godiddy.com:64c36bf4-2f08-4f8c-8e7b-c672d791e569 - web
  • did:indy:danube:AHzHqixnb7mr9SSZXHpxhW - indy
  • did:hedera:testnet:z8Wkv5GeszUBSM3vnS1713kBDTaCKezwEXzNkR3gLuA5w_0.0.3559453 - hedera

The DID to be resolved, or the DID URL to be dereferenced.

header Parameters
accept
string

The requested media type of the DID document representation or DID resolution result. See https://www.w3.org/TR/did-core/#representations and https://w3c-ccg.github.io/did-resolution/#did-resolution-result.

  • application/json - Media type of a DID document (JSON representation).
  • application/did+ld+json - Media type of a DID document (JSON-LD representation).
  • application/ld+json;profile="https://w3id.org/did-resolution" - Media type of a DID resolution result (JSON-LD representation).

Responses

Response samples

Content type
application/json
Example
{
  • "@context": { },
  • "didResolutionMetadata": {
    },
  • "didDocument": {
    },
  • "didDocumentMetadata": {
    }
}

Events

Get activities

Retrieves activities for the current user. The results are sorted in reverse chronological order (ie most recent first) and paginated, with both items per page and the page to display being parameterized (passed in query string).

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "activities": [
    ],
  • "meta": {
    }
}

Get Events

Retrieves events for the current user. The results are sorted in reverse chronological order (ie most recent first) and paginated, with both items per page and the page to display being parameterized (passed in query string).

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "events": [
    ],
  • "meta": {
    }
}

Helpers

Obtain a signed upload URL

Create a signed upload URL for one of the supported file storages. This endpoint is the first step in creating a file.

Just like most ATOM endpoints, this endpoint requires a valid user (that is, an IDP JWT) and some security rights. The security rights are those which might require to attach files to entities like organisations, tenants, and so on. Any of the following security rights grants a permission to create an upload URL

  • atom:global:create_tenant
  • atom:global:create_org
  • atom:global:create_tenant_agent
  • atom:tenant:create_org
  • atom:tenant:create_agent
  • atom:org:create_agent
  • atom:tenant:create_tenant_agent
  • vc:tenant:manage
  • vc:org:manage

ATOM generates a random key under which a file will be registered, and creates a record in the database where the key is stored along with the filename and the content type. A client is then expected to use a signed URL present in response field upload_url to upload a file to a cloud file storage. This URL is only valid for a short period of time specified in response field upload_url_expires_in_seconds.

Uploading is done via HTTP method PUT. The response of this endpoint contains a list of headers which much be included in the PUT request.

The following is an example curl command to upload a file:

curl --location --request PUT \
'https://meecodevstorage0.blob.core.windows.net/dev/66c35456-eb64-42fb-a31a-806530786fe2?se=2023-01-23T08%3A49%3A29Z&sig=mzuonk01F8L%2F0q7avsMvvenk2NwLFVXYsyWJeu5Jdgc%3D&sp=rw&sr=b&sv=2018-11-09' \
--header 'x-ms-blob-type: BlockBlob' \
--data-binary '@/home/john/file.jpg'

After the file is uploaded to Azure Blob Storage, the client is supposed to confirm this upload calling PUT /blobs/{key}.

The response to POST /blobs also contains a URL to retrieve the file, but that functionality is only available after the upload has been confirmed, otherwise it will result in 404 NotFound.

All expired and not confirmed records created with this endpoint will be removed after a while.

Authorizations:
SVX-JWT
query Parameters
storage_name
required
string

Name of the file storage. This parameter so optional, if no name is specified, the default file storage is used

Request Body schema: application/json

File name and content type

content_type
string

content type of the file to be uploaded

filename
required
string

name of the file to be uploaded

Responses

Request samples

Content type
application/json
{
  • "content_type": "image/jpeg",
  • "filename": "logo.jpg"
}

Response samples

Content type
application/json
{
  • "blob": {
    }
}

Redirect to a file in a cloud file storage

Redirect to a file in a cloud file storage.

This endpoint is public and it only requires the file key in the URL.

The Content Disposition header in the response is hardcoded to be inline for now, but it can be made a parameter to this endpoint in future if needed. The filename and the content type included in Content Disposition are taken from the database record created in POST /blobs."

path Parameters
id
required
string

Blob key

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

Confirm a blob upload

Confirm a blob upload.

After a client retrieves an uploads URL via POST /blobs and uploads a file to that URL, a client is expected to inform ATOM that the upload is successful. The file is not accessible unless the upload is confirmed.

This call may only be performed by the same user who retrieved the upload URL.

The response to the endpoint contains one more upload URL. A client can use it to upload a newer version of the file under the same key. No confirmation is required in this case.

See documentation for POST /blobs for more information.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Blob key

Responses

Response samples

Content type
application/json
{
  • "blob": {
    }
}

View blob info

View information about the file.

This call may only be performed by the same user who retrieved the upload URL and uploaded the file.

Along with a URL to read the file the response to the endpoint contains one more upload URL. A client can use it to upload a newer version of the file under the same key. No confirmation is required in this case.

See documentation for POST /blobs for more information.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Blob key

Responses

Response samples

Content type
application/json
{
  • "blob": {
    }
}

View blob info

View public information about the file.

See documentation for POST /blobs for more information.

path Parameters
id
required
string

Blob key

Responses

Response samples

Content type
application/json
{
  • "blob": {
    }
}

Redirect to the logo of a tenant

Redirect to the logo of a tenant.

This endpoint is public and it only requires the tenant ID in the URL.

path Parameters
tenant_id
required
string <uuid>

Tenant ID

Responses

Response samples

Content type
application/json
{
  • "error": "unauthorized",
  • "extra_info": {
    },
  • "http_code": 401,
  • "message": null
}

Items

View attachments folders of the user

Read attachment folders of the user

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "attachments_folders": [
    ],
  • "meta": {
    }
}

Create an attachment folder

Creates an attachment folder, which represents a folder in a remote cloud file storage. An attachments folder can then be attached to a slot with type attachments_folder

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "attachments_folder": {
    }
}

Delete attachments folder

Delete an attachment folder if it is not attached to any slot

Authorizations:
SVX-JWT
path Parameters
id
required
string

Attachments Folder ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

View an attachment folder

Read an attachment folder

Authorizations:
SVX-JWT
path Parameters
id
required
string

Attachments Folder ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "attachments_folder": {
    }
}

Redirect to an attachment on an external blob storage

Generates a signed URL for an attachment on an external blob storage and redirects to it.

This endpoint is a single place for redirecting to external files of the following entities:

This endpoint is requires a session and verifies if the current user may access the attachment.

  • Attachments
  • Direct attachments (both the file itself and the encryption artifact file) A client application cannot programmatically build this HTTP request, because the logic of calculating the digest parameter is internal to the vault. Instead the vault generates URLs targeting this endpoint and adds them to JSON responses of the above objects.

The URL in the redirect header is a signed URL valid for 5 minutes.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Blob ID

d
required
string

A digest for the blob identified by the ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Redirect to an image or a thumbnail on an external blob storage

Generates a signed URL for a image or a thumbnail on an external blob storage and redirects to it.

This endpoint is not secured with a session token.

This endpoint is a single place for redirecting to external files of the following entities:

  • Images
  • Thumbnails

A client application cannot programmatically build this HTTP request, because the logic of calculating the digest parameter is internal to the vault. Instead the vault generates URLs targeting this endpoint and adds them to JSON responses of the above objects.

The URL in the redirect header is a signed URL valid for 5 minutes.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Blob ID

d
required
string

A digest for the blob identified by the ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Read the client task queue

A ClientTask represents a task the client is supposed to perform.

Field work_type represents a type of work, target_id points to the input argument of the task and its semantics depends on work_type.

Available work types are:

  • update_item_shares - In an update_item_shares task target_id points to an item. update_item_shares task is created when the item is updated. Clients are expected to re-encrypt encrypted values of the the shared items for all existing shares and update them.
  • setup_key_delegation - In an setup_key_delegation task target_id points to a delegation connection. setup_key_delegation task is created when a delegation connection is created. Clients are expected to share the users key encryption key with the delegate user. This task must be manually marked as done either via API or using convenience methods in the SDK
  • reencrypt_account_owner_kek - In an reencrypt_account_owner_kek task target_id points to a delegation connection. reencrypt_account_owner_kek task is created when a setup_key_delegation task is marked as complete after a key encryption key is shared
  • incoming_delegation_invitation - In an incoming_delegation_invitation task target_id points to a delegation invitation. incoming_delegation_invitation task is created when a new delegation invitation is created

Each ClientTask may have the following states:

  • todo
  • in_progress
  • done
  • failed

This endpoint serves client tasks ordered by created_at in descending order. It is possible to request tasks with a different state by providing an array of states to the parameter state.

All returned tasks with state todo may optionally be transitioned to state in_progress through by setting change_state=true.

All tasks with state in_progress are transitioned back to todo after a timeout of 10 minutes unless the state is changed to done or failed.

Authorizations:
SVX-JWT
query Parameters
next_page_after
string

cursor to get the next page

per_page
integer
Default: 200

override the number of records per page - default 200

change_state
boolean

transition tasks in the response to in_progress

target_id
string

search client tasks by target_id

state
Array of strings
Items Enum: "todo" "in_progress" "done" "failed"

States of tasks to return, provided as a comma separated list

work_type
string
Enum: "update_item_shares" "setup_key_delegation"

Return only client tasks of a certain type.

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "client_tasks": [
    ],
  • "meta": {
    }
}

Change the state of client tasks

Change the state of client tasks. Normally used to set tasks to done or failed. Along with the states the client can pass task execution reports. A report is a JSON object. A report can be useful for failed tasks.Responds with a non-paginated list of with the same tasks.

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
required
Array of objects (PutSharesRequestShare)

Responses

Request samples

Content type
application/json
{
  • "client_tasks": [
    ]
}

Response samples

Content type
application/json
{
  • "client_tasks": [
    ]
}

Create a file attachment

Create attachment record after uploading file the and its encrypted artifacts

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
object (PostCreateAttachmentBlobRequest)

Responses

Request samples

Content type
application/json
{
  • "blob": {
    }
}

Response samples

Content type
application/json
{
  • "attachment": {
    }
}

Retrieve a signed URL which allows a file upload from a client directly to the cloud storage

Retrieve a signed URL which allows a file upload from a client directly to the cloud storage

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
object (PostAttachmentDirectUploadUrlBlobRequest)

Responses

Request samples

Content type
application/json
{
  • "blob": {
    }
}

Response samples

Content type
application/json
{
  • "attachment_direct_upload_url": {
    }
}

Delete Attachment

Delete attachment record by id

Authorizations:
SVX-JWT
path Parameters
id
required
string

Attachment ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Retrieve a file attachment information and download URLs

Retrieve a file attachment information and the two download URLs. One file attachment record contains 2 files:

  • Main file
  • Encryption artefact file

The response contain 2 URLs to download these 2 files.

This endpoint may be used by

  • the user who created this file attachment
  • a user who has received a share with this attachment
Authorizations:
SVX-JWT
path Parameters
id
required
string

Attachment ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "attachment": {
    }
}

Redirect to an image

Authorizations:
SVX-JWT
path Parameters
id
required
string

Image ID

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Get Item Templates

Fetch public and current_user item templates

Authorizations:
SVX-JWT
query Parameters
by_classification[scheme]
string
by_classification[name]
string
like
string

search by item_template label term

next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Responses

Response samples

Content type
application/json
{
  • "next_page_after": "string",
  • "attachments": [
    ],
  • "thumbnails": [
    ],
  • "classification_nodes": [
    ],
  • "slots": [
    ],
  • "item_templates": [
    ],
  • "meta": {
    }
}

Create item template

Authorizations:
SVX-JWT
header Parameters
Meeco-Delegation-Id
string

Meeco-Delegation-Id contains the ID of a user that the current user has delegation permissions for. If delegation has been set up correctly, the current user of the action will be the user in Meeco-Delegation-Id

Meeco-Organisation-Id
string

This header is required for ATOM-based delegation. ATOM-based delegation enables administrators of an organisation to perform actions on behalf of an organisation. If this header is present, header Authentication must have a Security Rights Token (SRT) instead of a standard authentication JWT. An SRT may contain security rights for more than one organisation. In order for the user to be able to execute actions of behalf of the organisation specified in the header the user must have security right vk:org:delegation for this organisation.

Request Body schema: application/json
name
string
label
string
description
string
image_id
string
classification_scheme_name
string
classification_node_name
string
Array of objects (PostItemTemplateRequestSlotAttributes)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "label": "string",
  • "description": "string",
  • "image_id": "string",
  • "classification_scheme_name": "string",
  • "classification_node_name": "string",
  • "slots_attributes": [