API docs by Redocly

SVX API (1.3.5)

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
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
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
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 a user from organisation admins

Remove a user from organisation admins.

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

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

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

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

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 an organisation admin

Assign organisation security rights to an organisation admin.

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
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
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
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
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_token
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_token
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. 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 Azure Blob 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. Header x-ms-blob-type: BlockBlob must be present in this 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
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 Azure Blob Storage

Redirect to a file in Azure Blob 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": [
    ]
}

Response samples

Content type
application/json
{
  • "classification_nodes": [
    ],
  • "slots": [
    ],
  • "item_template": {
    },
  • "attachments": [
    ],
  • "thumbnails": [
    ]
}

Get item template

Get an item template specified by id.

Authorizations:
SVX-JWT
path Parameters
id
required
string

ItemTemplate 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_nodes": [
    ],
  • "slots": [
    ],
  • "item_template": {
    },
  • "attachments": [
    ],
  • "thumbnails": [
    ]
}

Get items

Fetch items that the current user has access to

Authorizations:
SVX-JWT
query Parameters
template_ids
string

a list of template IDs separated by commas

name
string

if present, only items with this name are fetched

classification_scheme_name
string

if present, only items classified according to the given classification scheme are fetched

classification_node_name
string

if present, only items classified with a classification node with the given name are fetched. Cannot be used together with classification_node_names filter.

classification_node_names
string

if present, only items classified with classification node with the given names are fetched.Supports a list of string values separated by commas. Cannot be used together with classification_node_name filter.

shared_with
string

The ID of a user. If present, only items will be fetched which have been shared with the given user. Works for items owned by the current user as well as for items owned by someone else and on-shared by the current user.

owner_id
string

The ID of a user. If present, only items will be fetched which belong to the given user. This parameters makes it possible see a subset of items shared with the current user which belong to a specific user.

own
string

Can be true, 1, false, or 0. If true, only your own items are fetched. if false, only items shared with the current user are fetched.

item_ids
string

A list of comma separated item IDs to filter by.

next_page_after
string

cursor to get the next page

per_page
integer

override the number of records per page - default 200

order
string

sort order, can be asc or desc. The default is asc.

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": [
    ],
  • "items": [
    ],
  • "meta": {
    }
}

Create an item

Create an item populated with slots. There are 3 top-level parameters:

  • item - input data to create an item and its slots.

  • template_name. Each item is cloned from an item template. The name of the item template must be present in this field. In addition to data copied from the item template, template slots become item slots.

  • skip_empty_template_slots. If true, then only those template slots will be created for which incoming parameters are present. Otherwise all template slots become item slots.

The parameters in item are as follows:

  • label is a human-readable name. label is mandatory
  • name is a machine reference. It can be skipped, in that case name from the template will be used
  • description can be skipped, in that case description from the template will be used
  • slots_attributes. Parameters in slots_attributes can be used either to create new slots or update slots cloned from the template slots. slots_attributes can be empty, in this case the newly created item will only contain slots cloned from the template
  • classification_nodes_attributes

Matching incoming slot parameters to slots cloned from the template

There are 2 cases when slot parameters are used to update an already existing slot cloned from the template:

  1. If slot_type_id inside parameters for a slot matches slot_type_id of a cloned slot, the parameters will be used to update the matched slot.
  2. If name inside parameters for a slot matches name of a cloned slot, the parameters will be used to update the matched slot.

In all other cases slot parameters will be used to create a new slot.

Classifications

In this endpoint it is possible to link the item and its slots to classification nodes, and to create classification nodes in user-owned classification schemes if they do not exist yet.

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

There are 5 parameters for classification of slots and items in POST /items:

  • id

  • name

  • scheme

  • scheme_name

  • label Both a classification scheme and a classification node can be referred to by their name or their ID. If id is used, scheme_id and scheme may be omitted.

Example payload classifications:

classification_nodes_attributes: [
  {id: "c1b1d2b3-a887-4cc2-86e8-285268df598a"},
  {scheme: "region", id: "315e4e30-93f0-4232-b977-b51f90b18288"},
  {scheme: "region", name: "france"},
  {scheme: "tag", name: "Holiday Locations"},
  {scheme_id: "34c8c951-aa25-4d9a-9a9a-dbb5f43b821b", name: "netherlands"},
  {scheme_id: "34c8c951-aa25-4d9a-9a9a-dbb5f43b821b", id: "16557bff-21fe-4bb1-8b0a-0a7847dfc7d6"},
  {scheme: "tag", name: "my-own-cool-tag"}
]

If node france is missing in scheme region, the service will return an error, because scheme region is a global scheme. (owned_by_user=false). If node my-own-cool-tag is missing in scheme tag, it will be created, because scheme tag is a user owned scheme.

Here is an example of a minimalistic POST request to this endpoint:

{
  "template_name": "template-name",
  "item": {
    "label": "new-item-label"
  }
}

With one slot:

{
  "template_name": "template-name",
  "item": {
    "label": "new-item-label",
      "slots_attributes": [
        "label": "a label",
        "encrypted_value": "user-encrypted-value"
      ]
  }
}
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
object (PostItemsRequestItem)
skip_empty_template_slots
boolean

by default all template slots are copied to the item. If skip_empty_template_slots is true, empty template slots will not be created

template_name
required
string

Responses

Request samples

Content type
application/json
{
  • "item": {
    },
  • "skip_empty_template_slots": true,
  • "template_name": "string"
}

Response samples

Content type
application/json
{
  • "attachments": [
    ],
  • "classification_nodes": [
    ],
  • "item": {
    },
  • "slots": [
    ],
  • "thumbnails": [
    ]
}

Delete an item

Delete an item.

If the item is an item shared with the current user, the corresponding share is deleted together with the item.

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 Item

Retrieve a specific Item by id.

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
{
  • "attachments": [
    ],
  • "classification_nodes": [
    ],
  • "item": {
    },
  • "slots": [
    ],
  • "thumbnails": [
    ]
}

Update an item

Update an Item specified by id with fields provided in the JSON body.

Classifications

In this endpoint it is possible to link the item and its slots to classification nodes, unlink the item and its slots from classification nodes, and to create classification nodes in user-owned classification schemes if they do not exist yet.

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

There are 5 parameters for classification of slots and items in POST /items:

  • node_id
  • node_name
  • scheme_id
  • scheme_name
  • _destroy

Both a classification scheme and a classification node can be referred to by their name or their ID. If id is used, scheme_id and scheme may be omitted.

Flag _destroy is used to unlink a classification node from a slot or the item.

Example payload classifications:

classification_nodes_attributes: [
  {id: "c1b1d2b3-a887-4cc2-86e8-285268df598a"},
  {scheme: "region", id: "315e4e30-93f0-4232-b977-b51f90b18288"},
  {scheme: "region", name: "france", "_destroy": true},
  {scheme_id: "34c8c951-aa25-4d9a-9a9a-dbb5f43b821b", name: "netherlands"},
  {scheme_id: "34c8c951-aa25-4d9a-9a9a-dbb5f43b821b", id: "16557bff-21fe-4bb1-8b0a-0a7847dfc7d6"},
  {scheme: "tag", name: "my-own-cool-tag"}
]

If node france is missing in scheme region, the service will return an error, because scheme region is a global scheme. (owned_by_user=false). If node my-own-cool-tag is missing in scheme tag, it will be created, because scheme tag is a user owned scheme.

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.

Request Body schema: application/json
object (PutItemsRequestItem)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "attachments": [
    ],
  • "classification_nodes": [
    ],
  • "item": {
    },
  • "slots": [
    ],
  • "thumbnails": [
    ]
}

View attachments folder linked to a slot

Read an attachment folder linked to a slot

Authorizations:
SVX-JWT
path Parameters
id
required
string

Slot 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": {
    }
}

Keys

Stores a data encryption key

Stores a data encryption key encrypted with the key encryption key (KEK) of the user. The expected format is the serialization format of the Cryppo library.

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
serialized_data_encryption_key
required
string

Responses

Request samples

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

Response samples

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

Deletes a data encryption key

Deletes a data encryption key identified by its ID.

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": [
    ]
}

Retrieves a data encryption key

Retrieves a data encryption key by its ID.The data encryption key is encrypted with the key encryption key (KEK) of the user. The format is the serialization format of the Cryppo library.

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
{
  • "data_encryption_key": {
    }
}

Retrieves a key encryption key (KEK)

Returns a key encryption key (KEK) encrypted with the passphrase derived key of the user. The format is the serialization format of the Cryppo library.

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
{
  • "key_encryption_key": {
    }
}

Stores a key encryption key (KEK)

Stores a key encryption key (KEK) encrypted with the passphrase derived key of the user. The expected format is the serialization format of the Cryppo library.

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
serialized_key_encryption_key
required
string

Responses

Request samples

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

Response samples

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

Stores a keypair

Stores a keypair. The keypair encrypted with the key encryption key (KEK) of the user (field encrypted_serialized_key). The format is the serialization format of the Cryppo library. Also stores the public key unencrypted as a PEM or any other format. Each keypair can be tagged by a list of tags which make is possible for the client to differentiate between various keypairs.

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
encrypted_serialized_key
string

Serialized encrypted key

public_key
string
metadata
object
external_identifiers
Array of strings

Responses

Request samples

Content type
application/json
{
  • "encrypted_serialized_key": "string",
  • "public_key": "string",
  • "metadata": { },
  • "external_identifiers": [
    ]
}

Response samples

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

Retrieves a keypair by external id

Retrieves a KeyPair specified by external_id (eg the id for a Connection, if the KeyPair was created for that purpose).

Authorizations:
SVX-JWT
path Parameters
external_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
{
  • "keypair": {
    }
}

Deletes a keypair

Deletes a keypair identified by its ID.

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": [
    ]
}

Retrieves a keypair

Retrieves a keypair identified by its ID. The keypair encrypted with the key encryption key (KEK) of the user (field encrypted_serialized_key). The format is the serialization format of the Cryppo library. The public key is also served unencrypted as a PEM or any other serialization format

Authorizations:
SVX-JWT
path Parameters
id
required
string
query Parameters
external_id
string

if a keypair is not found by ID and this optional parameter is present, the keystore will attempt to find a keystore by external_id in this parameter. This parameter can also be a solution for a case when there is some ID and we don't know whether this is an ID or an external ID of a keypair. In this case we can put this ID in id in the path and external_id in the query.

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
{
  • "keypair": {
    }
}

Updates a keypair

Updates fields for KeyPair specified by id with new values if provided in params.

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.

Request Body schema: application/json
external_identifiers
Array of strings
metadata
object

Responses

Request samples

Content type
application/json
{
  • "external_identifiers": [
    ],
  • "metadata": { }
}

Response samples

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

Retrieves the passphrase derivation artefact for the current user

Returnes passphrase derivation artefacts which were used for generation of the passphrase derived key.The format is as a JSON string encoded as Base64 (urlsafe).

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
{
  • "passphrase_derivation_artefact": {
    }
}

Stores passphrase derivation artefacts

Passphrase derivation artefacts used for generation of the passphrase derived key are expected to be sent as a JSON string encoded as Base64 (urlsafe) a field of the payload to this endpoint.

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
derivation_artefacts
required
string
verification_artefacts
required
string

Responses

Request samples

Content type
application/json
{
  • "derivation_artefacts": "string",
  • "verification_artefacts": "string"
}

Response samples

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

Metrics

Obtain the report on the size of attachments and slots

Obtain the report on the size of attachments created by the current user, and the size of attachments linked to slots owned by the user as well as slots shared with the user.

The unit is bytes.

One and the same attachment or a folder can be linked to multiple slots. One such case is share duplicate slots. With this report it is possible to count only unique attachments and folders, as well as count references to the same attachment/folder as if they were separate files. See model UserAttachmentsReport for details.

The report takes into account the following:

  • attachments
  • all files in folders

The report currently does not take into account the following:

  • encryption artifact files of attachments
  • thumbnails of attachments
  • images attached to slots
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
{
  • "attachment_metrics": {
    }
}

Obtain connection report

Obtain connection report for the currently authenticated 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
{
  • "connection_metrics": {
    }
}

Obtain a report on user's items and slots

Obtain a report on currently authenticated user's items and slots

Authorizations:
SVX-JWT
query Parameters
template_ids
string

a list of template IDs separated by commas

classification_scheme_name
string

if present, only items classified according to the given classification scheme are counted

classification_node_name
string

if present, only items classified with a classification node with the given name are counted. Cannot be used together with classification_node_names filter.

classification_node_names
string

if present, only items classified with classification node with the given names are counted.Supports a list of string values separated by commas. Cannot be used together with classification_node_name filter.

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
{
  • "item_metrics": {
    }
}

Security Rights

List all users with global security rights

List all users with global security rights.

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

In order to execute this action the current user must have "security right atom:global:assign_global_sr_to_user.

Authorizations:
SVX-JWT
query Parameters
email
string

search admins by their email address

status
string
Enum: "active" "archived"

admin status: active or archived

per_page
integer

number of admins per page

order
string
Enum: "asc" "desc"

order admins 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.

Responses

Response samples

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

Remove a user from global admins

Remove a user from global admins, that is, remove all global security rights from a user.

In order to execute this action the current user must have security right atom:global:assign_global_sr_to_user.

Authorizations:
SVX-JWT
path Parameters
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 a user with global security rights

Show a user with global security rights

In order to execute this action the current user must have "security right atom:global:assign_global_sr_to_user.

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

ID of the admin

Responses

Response samples

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

Archive a global admin

Remove a user from global admins, and put the admin into the registry of former global admins.

In order to execute this action the current user must have security right atom:global:assign_global_sr_to_user.

Authorizations:
SVX-JWT
path Parameters
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 global admin

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

In order to execute this action the current user must have security right atom:global:assign_global_sr_to_user.

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

ID of the admin

Responses

Response samples

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

Assign global security rights to a user

Assign global security rights to a user.

The user we are assigning security rights to does not need to be known by ATOM.

In order to execute this action the current user must have security right atom:global:assign_global_sr_to_user.

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

ID of a user to whom security rights are assigned

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
}

Remove global security rights from a user

Remove global security rights from a user.

In order to execute this action the current user must have security right atom:global:assign_global_sr_to_user.

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

ID of a user from whom security rights are removed

security_rights
required
string

List of comma-separated security rights to remove

Responses

Response samples

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

All security rights of the current user

Show all security rights of the current user for all active tenants and organizations

Authorizations:
SVX-JWT

Responses

Response samples

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

Show all security rights known to ATOM

Show all security rights known to ATOM

query Parameters
with_inactive
boolean

By default only active security rights are fetched. with_inactive allows to retrieve all security rights including inactive.

Responses

Response samples

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

Shares

Read incoming shares

Read incoming shares as the recipient.

Only share records are fetched. Shared items and slots appear in the main feed of users's items.

Some shares require that the recipient accepts the terms of the share. This behavior is controled by field acceptance_required. By default all incoming shares are fetched, but you can also specify parameter acceptance_required=acceptance_required in order to only read shares which require acceptance.

Other possible states are:

  • acceptance_not_required
  • accepted
  • rejected

The encrypted_dek for a share slot may be null for the following reasons:

  1. If the state is acceptance_required the encrypted_dek is intentionally hidden until accepted
  2. If the slot has been re-encrypted via POST /items/{id}/encrypt, a null encrypted_dek means the slot is encrypted with the current user's DEK instead
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

order
string

sort order, can be asc or desc. The default is desc.

own_connection_id
string

Only show shares from the user connected via the connection with the given ID

acceptance_required
string

one of the following states: * acceptance_not_required * acceptance_required * accepted * rejected

share_ids
string

A list of share IDs joined with a comma

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",
  • "shares": [
    ],
  • "meta": {
    }
}

Read an incoming share

Read an incoming share as the recipient.

Only a share record is fetched. The item and slots created for the current user (receiver) according to this share are not served. To retrieve the share with the item and slot records created for the share recipient use GET /incoming_shares/{id}/item.

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
{
  • "share": {
    }
}

Accept share terms

Accept share terms.

Some shares require that the recipient accepts the terms of the share. Until the terms are not accepted the share DEK is hidden.

Via this endpoint a recipient can accept terms of a share.

Authorizations:
SVX-JWT
path Parameters
id
required
string

ID of the share

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
{
  • "share": {
    }
}

Read an incoming share together with the shared item and slots

Read an incoming share together with shared item, slots, and other associated data.

One and the same item can be shared to a recipient via different shares.

This endpoint renders the shared item in both cases, whether the item has been shared via the current share or via a different share of the same item.

In case the shared item has been shared via the current share then field item_shared_via_another_share_id is NULL.

If the item has been shared via a different share field item_shared_via_another_share_id contains the ID of that share and the client is advised to re-run the call with this ID.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Share 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
{
  • "share": {
    },
  • "item_shared_via_another_share_id": "string",
  • "attachments": [
    ],
  • "classification_nodes": [
    ],
  • "item": {
    },
  • "slots": [
    ],
  • "thumbnails": [
    ]
}

Create one or more share intents

Creating share intent is part of the Single Step Connection and Sharing flow.

The Single Step Connection and Sharing flow allows to create a connection to a user and share an item in one go. The main steps of the Single Step Connection and Sharing flow are as follows:

  1. The share sender creates a regular invitation with POST /invitations
  2. The share sender creates a share intent linking it to the invitation
  3. The share recipient accepts the invitation via POST /connections, just like any regular invitation
  4. The vault creates a connection between the sender and the recipient, and creates a share

In addition to invitation_id the share intent contains all the data needed to create the share once the invitation is accepted:

  1. encrypted_dek - Data encryption key for the shared data. The key is encrypted with the token PDK (see below for more details).
  2. item_id - ID of the item that will be shared. Identical to item_id in POST /items/{id}/shares
  3. slot_id - ID of the slot that will be shared. Present if only one slot will be shared. NULL if all slots of the item are to be shared. Identical to slot_id in POST /items/{id}/shares
  4. slot_values - Encrypted slot data in the same format used in POST /items/{id}/shares. The data is encrypted with the share DEK.
  5. onsharing_permitted - Sharing mode of the share. Identical to onsharing_permitted in POST /items/{id}/shares
  6. expires_at - Expiration date of the share.

Slot data in a regular share is initially encrypted with a dedicated share DEK. This share DEK is encrypted with the public key of the share recipient, taken from the connection record between the two users. In case of a share intent there is no connection yet, and no recipient public key is available yet, so there is a different workflow. There is still a dedicated share DEK, and it is stored right in the share intent record in the encrypted form. How exactly it is encrypted depends on which invitation workflow, simple invitation workflow or multistep invitation workflow. In the simple invitation flow the sender generates a short passphrase, derives a DEK from this short passphrase, and uses this derived DEK to encrypt the share DEK. In the multistep invitation flow the key exchange looks as follows:

  1. The sender generates a share DEK
  2. The sender encrypts share data with that DEK
  3. The sender encrypts the share DEK with their private DEK. At this stage no one but the sender can decrypt this share DEK
  4. After the recipient accepts the invitation, the sender confirms the invitation. At this stage the connection record is created abd both public keys are available. When confirming the invitation, the sender decrypts the share DEK with their private DEK, re-encrypts it with the public key of the recipient, and shares created from these share intents contain this version of the DEK encrypted with the public key of the recipient.
Authorizations:
SVX-JWT
path Parameters
invitation_id
required
string

ID of the linked invitation

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
Array of objects (ShareIntentParam)

Responses

Request samples

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

Response samples

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

Re-encrypt share data

Re-encrypt share data

Data in shared slots is initially encrypted with the share DEK. The share DEK is encrypted with the public key of the share recipient. When processing a share the client application is expected to decrypt the slot data as well as encrypted_value_verification_key and re-encrypt with them private DEK with this endpoint.

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.

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "attachments": [
    ],
  • "classification_nodes": [
    ],
  • "item": {
    },
  • "slots": [
    ],
  • "thumbnails": [
    ]
}

Prepare an update of all shares of one item

Updating all shares of one item is done by the item owner in one go.

A share DEK is encrypted with a public key of the recipient. In order to update shares the owner needs a public key of the recipient of each share. But some shares may be created by users different from the owner, and thus the owner might have no connection to recipients of those shares, and no access to those shares.

This problem is solved by

  • Putting a public key of the recipient and an identification of the keypair to which the public key belongs into each share record.
  • Providing a list of all public keys and share IDs for all shares of the given item via this endpoint

Getting this list is the first step in updating all shares of the item.

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
{
  • "shares": [
    ]
}

Share your item with connected users

Share your item with connected users.

Each share can be a share of all slots of the item, in that case slot_id is NULL, or it can be a share of just one slot. In this case slot_id references one of the slots of the item.

There are 3 users involved in each share:

  • owner - the owner of the shared item
  • sender - the user who shares data. Can be the owner or one of the recipients
  • recipient - the user who recieves the shared data.

Whether a non-owner may on-share a shared slot is defined in field onsharing_permitted.

Only the owner of the item can set onsharing_permitted to true. If onsharing_permitted is false, the recipient may on-share the item, but when that recipient creates an on-share, onsharing_permitted in that on-share is forced to be false. In other words, the depth of on-sharing in limited to 3:

OWNER ==> RECIPIENT AND SENDER ==>  RECIPIENT

Some shares require that the recipient accepts the terms of the share. Until the terms are not accepted the share DEK is hidden.

Data in slots is initially encrypted with the DEK in field encrypted_dek. The DEK in encrypted_dek is encrypted with the public key of the share recipient. When processing a share the client application is expected to decrypt the slot data and re-encrypt with the private DEK.

A public key of the recipient is needed to encrypt the share DEK. Updating all shares of the same item is performed by the owner in one go. In a situation when a share has been created by a recipient, not the owner, and there is no connection between the owner and the recipient, the owner has no access to a public key of the recipient. In order to address this problem when a share is created we also add fields public_key and keypair_external_id from the connection record between the recipient and the sender. keypair_external_id identifies the keypair that the public key belongs to.

When a recipient of a share on-shares the data with someone else, nothing prevents him/her to encrypt some other data instead of the original data. We need a way to enforce integrity of on-shares. We do this with help of HMAC - hash-based message authentication code obtained by running a cryptographic hash function over the data and a shared secret key.

Two fields in each slot are used for this purpose:

  • encrypted_value_verification_key - is a value verification key encrypted in the same way as the value itself: with the share DEK
  • value_verification_hash - the result of the HMAC function run on the slot value using encrypted_value_verification_key. value_verification_hash is stored as-is, unencrypted.

Only the owner of the data may send value_verification_hash when creating or updating the share. When other senders create a share, value_verification_hash must be NULL.

encrypted_value_verification_key may and should be sent by every sender, owner or not, because encrypted_value_verification_key must be re-encrypted with the share DEK for each share.

If the sender replaces encrypted_value_verification_key and/or the slot value, this will break the client-side verification against encrypted_value_verification_key. Field encrypted_value may be NULL. If encrypted_value is NULL, then encrypted_value_verification_key and value_verification_hash may also be NULL. If encrypted_value is present, then encrypted_value_verification_key and value_verification_hash are mandatory.

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.

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

Responses

Request samples

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

Response samples

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

Update all shares of one item

Updating all shares of one item is done by the item owner in one go.

Before calling this endpoint the client application is expected to retrieve the list of shares IDs and public keys via GET /items/{id}/shares.

The POST body of this endpoint contains

  • a list of share DEKs encrypted with public keys of share recipients
  • a list of slot values for each slot and each share, each encrypted with the DEK of the share that the slot belongs to
  • Optionally: a list of completed ClientTask tasks

When a recipient of a share on-shares the data with someone else, nothing prevents him/her to encrypt some other data instead of the original data. We need a way to enforce integrity of on-shares. We do this with help of HMAC - hash-based message authentication code obtained by running a cryptographic hash function over the data and a shared secret key.

Two fields in each slot are used for this purpose:

  • encrypted_value_verification_key - is a value verification key encrypted in the same way as the value itself: with the share DEK
  • value_verification_hash - the result of the HMAC function run on the slot value using encrypted_value_verification_key. value_verification_hash is stored as-is, unencrypted.

Only the owner of the data may send value_verification_hash when creating or updating the share. When other senders create a share, value_verification_hash must be NULL.

encrypted_value_verification_key may and should be sent by every sender, owner or not, because encrypted_value_verification_key must be re-encrypted with the share DEK for each share.

If the sender replaces encrypted_value_verification_key and/or the slot value, this will break the client-side verification against encrypted_value_verification_key.

Field encrypted_value may be NULL. If encrypted_value is NULL, then encrypted_value_verification_key and value_verification_hash may also be NULL. If encrypted_value is present, then encrypted_value_verification_key and value_verification_hash are mandatory.

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.

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

New deks for shares

Array of objects (PutItemSharesRequestShareSlotValues)

New shared item slot values per share

Array of objects (PutItemSharesClientTasksRequest)

Responses

Request samples

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

Response samples

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

Read outgoing shares

Read outgoing shares. That is, all shares the current user has created, including on-shares.

Only share records are fetched.

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

order
string

sort order, can be asc`` or desc``. The default is desc.

own_connection_id
string

Only show shares shared with the user who is connected via the connection with the given ID

item_ids
Array of strings <uuid>

Search outgoing shares by given item ids. Limited to max of 10 ids per single request

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",
  • "shares": [
    ],
  • "meta": {
    }
}

Read an outgoing share

Read an outgoing share as the sender.

Only a share record is fetched.

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
{
  • "share": {
    }
}

View share intents the user has created

share intents the user has created

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",
  • "share_intents": [
    ],
  • "meta": {
    }
}

Delete a share intent

Delete a share intent

Authorizations:
SVX-JWT
path Parameters
id
required
string

Share intent 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 a share intent

Read an share intent

Authorizations:
SVX-JWT
path Parameters
id
required
string

Share intent 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
{
  • "share_intent": {
    }
}

Create shares of an item, re-configure shares, delete shares

This endpoint allows to perform three operations in one go:

  1. share your item with connected users. The ID of the item is in field item_to_share_id, and the share data is in shares_to_create
  2. delete existing shares by submitting a list of share IDs in field shares_to_delete
  3. change expiration and the on-sharing configuration of a list of shares (reconfiguring shares) by submitting a list of params in field shares_to_reconfigure

This endpoint is transactional, that is, if a 4xx response is returned and the error comes from one of these three actions (deletion of shares, reconfiguration of shares, creation of new share are), no other action will be executed. Each operation is optional. In order to skip creation of new shares set item_to_share_id to NULL.To read more about each operation please refer to the documentation of the following endpoints:

  1. sharing your item with connected users: POST /items/{id}/shares
  2. deletion of shares: DELETE /shares/{id}
  3. reconfiguring shares: PUT /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
shares_to_delete
Array of strings <uuid>

a list of IDs of shares to be deleted

Array of objects (ReconfigureShareParams)

List share params

item_to_share_id
string <uuid>
Array of objects (PostItemSharesRequestShare)

Responses

Request samples

Content type
application/json
{
  • "shares_to_delete": [
    ],
  • "shares_to_reconfigure": [
    ],
  • "item_to_share_id": "f9518723-5c32-49c1-8d96-1a3d276952a1",
  • "shares_to_create": [
    ]
}

Response samples

Content type
application/json
{
  • "created_shares": [
    ],
  • "deleted_shares": [
    ],
  • "reconfigured_shares": [
    ]
}

Modify expiration and on-sharing of a share

This endpoint permits changing settings of an existing share:

  • expires_at
  • onsharing_permitted

onsharing_permitted can be changed by the owner of the shared item only. If it is true, the recipient may on-share the item, but when that recipient creates an on-share, onsharing_permitted in that on-share is forced to be false. In other words, the depth of on-sharing in limited to 3:

OWNER ==> RECIPIENT AND SENDER ==>  RECIPIENT

If the owner of the item changes onsharing_permitted from true to false and there are existing on-shares, those on-shares are deleted.

Changing share expiration may be done by any share sender, both the owner of the item and a recipient, but there are 2 rules:

  • If the owner changes expiration to an ealier moment, expiration of all on-shares is also changed
  • A recipient of a share may not change expiration of his/her on-share to a timestamp earlier than the expiration of the share that the recipient has received.
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
Array of objects (ReconfigureShareParams)

List share params

Responses

Request samples

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

Response samples

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

Delete a share

Delete a share. Both the owner of the shared data and the recipient of the share may delete it.

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": [
    ]
}

Tenants

List all tenants

List all tenants.

In order to execute this action the current user must have security right atom:global:view_all_tenants.

Authorizations:
SVX-JWT
query Parameters
status
string
Enum: "active" "archived" "all"

tenant status: active, archived, or all

per_page
integer

number of tenants per page

order
string
Enum: "asc" "desc"

order tenants 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 tenants whose names contains the given string.

Responses

Response samples

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

Create a tenant

Create a tenant.

In order to execute this action the current user must have security right atom:global:create_tenant.

Authorizations:
SVX-JWT
Request Body schema: application/json

Tenant attributes

authorised_officer_email
string or null [ 0 .. 72 ] characters

Authorised officer email

authorised_officer_first_name
string or null [ 0 .. 72 ] characters

Authorised officer first name

authorised_officer_last_name
string or null [ 0 .. 72 ] characters

Authorised officer last name

business_address
string or null [ 0 .. 72 ] characters

Business address

color
string or null [ 0 .. 20 ] characters

The color associated with the tenant. Used for the UI.

company_number
string or null [ 0 .. 72 ] characters

Company number

id
string <uuid>

ID of the tenant. This parameter is optional. If missing, ATOM will choose a random UUID

legal_name
string or null [ 0 .. 72 ] characters

Legal number

lei_number
string or null [ 0 .. 72 ] characters

Legal entity identification number

logo_url
string or null <uri>

URL to a logo image

name
required
string

Name of the tenant

status_in_tenant
string or null [ 0 .. 72 ] characters

Status: signed legal agreement received or proof of concept

trading_name
string or null [ 0 .. 72 ] characters

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",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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
{
  • "tenant": {
    }
}

Delete a tenant

Delete a tenant.

In order to execute this action the current user must have security right atom:global:create_tenant.

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

ID of the tenant

Responses

Response samples

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

Show a tenant

Show a tenant.

In order to execute this action the current user must have either global security right atom:global:view_all_tenants or tenant security right atom:tenant:view_tenant.

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

ID of the tenant

Responses

Response samples

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

Update a tenant

Update a tenant.

In order to execute this action the current user must have security right atom:global:create_tenant.

It is possible to modify 3 fields:

  • name
  • logo_url
  • color
Authorizations:
SVX-JWT
path Parameters
id
required
string <uuid>

ID of the tenant

Request Body schema: application/json

Tenant attributes

authorised_officer_email
string or null [ 0 .. 72 ] characters

Authorised officer email

authorised_officer_first_name
string or null [ 0 .. 72 ] characters

Authorised officer first name

authorised_officer_last_name
string or null [ 0 .. 72 ] characters

Authorised officer last name

business_address
string or null [ 0 .. 72 ] characters

Business address

color
string or null [ 0 .. 20 ] characters

The color associated with the tenant. Used for the UI.

company_number
string or null [ 0 .. 72 ] characters

Company number

id
string <uuid>

ID of the tenant. This parameter is optional. If missing, ATOM will choose a random UUID

legal_name
string or null [ 0 .. 72 ] characters

Legal number

lei_number
string or null [ 0 .. 72 ] characters

Legal entity identification number

logo_url
string or null <uri>

URL to a logo image

name
required
string

Name of the tenant

status_in_tenant
string or null [ 0 .. 72 ] characters

Status: signed legal agreement received or proof of concept

trading_name
string or null [ 0 .. 72 ] characters

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",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "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
{
  • "tenant": {
    }
}

List admins of a tenant

List admins of a tenant.

In order to execute this action the current user must have

In order to execute this action the current user must have security right atom:tenant:list_tenant_admins 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"

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

order
string
Enum: "asc" "desc"

order admins by given 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.

Responses

Response samples

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

Remove a user from tenant admins

Remove tenant admin privileges from a tenant admin.

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

  • atom:global:assign_tenant_sr_to_tenant_admin
  • atom:tenant:assign_tenant_sr_to_tenant_admin
Authorizations:
SVX-JWT
path Parameters
tenant_id
required
string <uuid>

ID of the tenant

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 tenant

Show an admin of a given tenant

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

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

ID of the tenant

id
required
string <uuid>

ID of the admin

Responses

Response samples

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

Archive a tenant admin

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

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

  • atom:global:assign_tenant_sr_to_tenant_admin
  • atom:tenant:assign_tenant_sr_to_tenant_admin
Authorizations:
SVX-JWT
path Parameters
tenant_id
required
string <uuid>

ID of the tenant

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 tenant admin

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

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

  • atom:tenant:assign_tenant_sr_to_tenant_admin
  • atom:global:assign_tenant_sr_to_tenant_admin
Authorizations:
SVX-JWT
path Parameters
tenant_id
required
string <uuid>

ID of the tenant

id
required
string <uuid>

ID of the admin

Responses

Response samples

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

Assign tenant security rights to a tenant admin

Assign tenant security rights to a user.

The user we are assigning security rights to does not need to be known by ATOM.

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

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

ID of the tenant

tenant_admin_id
required
string <uuid>

ID of a tenant 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 a tenant

Archive a tenant.

In order to execute this action the current user must have security right atom:global:create_tenant.

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

ID of the tenant

Responses

Response samples

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

Restore a tenant

Restore a tenant.

In order to execute this action the current user must have security right atom:global:create_tenant.

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

ID of the tenant

Responses

Response samples

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

Add security rights to a tenant

Add security rights to a tenant.

In order to execute this action the current user must have security right atom:global:assign_sr_to_tenant.

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

ID of the tenant

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
{
  • "tenant": {
    }
}

Remove security rights from a tenant

Remove security rights from a tenant.

In order to execute this action the current user must have security right atom:global:assign_sr_to_tenant.

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

ID of the tenant

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
}

Users

Delete currently logged in end user from the tenancy

Deletes currently logged in from the tenancy. After running this action end user will not be able to authenticate against the tenancy anymore.

Admin can send a new invitation to the user and data will be restored.

Authorizations:
SVX-JWT

Responses

Response samples

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

Fetch information about currently logged in end user.

Fetch information about currently logged in end user. Response includes information about all the tenants end user is a member of.

Authorizations:
SVX-JWT

Responses

Response samples

Content type
application/json
{
  • "id": "16611f81-5e93-4156-a913-43c45192da27",
  • "did": "did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK",
  • "created_at": "2019-08-24T14:15:22Z",
  • "tenant_in_jwt": {
    },
  • "joined_tenants": [
    ]
}

List end users

List all end users that belong to a selected tenant.

Authorizations:
SVX-JWT
query Parameters
status
string
Enum: "active" "deleted" "all"
Example: status=active

End user status filter

search
string
Example: search=did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

End user search by DID filter

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

Responses

Response samples

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

List end user invitations

List end user invitations for the current tenant.

Authorizations:
SVX-JWT
query Parameters
status
string
Example: status=pending

Filter invitation by status attribute: e.g. pending,expired.
Available values: pending, accepted, expired.
To filter by more than one status separate values by using comma.

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

Responses

Response samples

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

Invite end user to join the tenancy

Creates an invitation for an end user to join the tenancy.

Authorizations:
SVX-JWT

Responses

Response samples

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

Exchange invitation token with a short lived access token

Exchange invitation token for a short lived access token that allows Wallet to complete registration flow.

Short lived access token is valid for a minute and can be used to:

  • verify the request via POST /oidc/presentations/requests/verify
  • generate a verifiable presentation via POST /presentations/generate
  • generate an ID Token via POST /oidc/presentations/token
  • acccept an invitation and get a longer lasting access token to use in the joined tenancy via POST /invitations/{token}/accept

Request Body schema: application/json
required
object (IDPGenerateShortLivedAccessTokenDto)

Responses

Request samples

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

Response samples

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

Delete the end user invitation

Deletes a pending or expired end user invitation.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

Fetch information about the end user invitation

Fetch information about the end user invitation.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

Accept invitation by submitting presentation request response

Accept invitation by submitting presentation request response.

If user is already a member of a tenant, invitation status will not change and only access token will returned.

Authorizations:
SVX-JWT
path Parameters
token
required
string
Request Body schema: application/json
id_token
required
string
vp_token
string
state
string

Responses

Request samples

Content type
application/json
{
  • "id_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "vp_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "state": "state-value"
}

Response samples

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

Fetch end user information by id

Fetch end user information by id.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

Delete end user from the tenancy by id

Deletes from the tenancy by id. After running this action end user will not be able to authenticate against the tenancy anymore.

Admin can send a new invitation to the user and data will be restored.

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

Delete an account

Delete the account associated with the currently authenticated 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
{
  • "errors": [
    ]
}

Show current user

Returns account details for the currently authenticated 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
{
  • "user": {
    },
  • "data_size_of_uploaded_attachments_and_folders": 0,
  • "data_size_limit": 0,
  • "data_size_limit_exceeded": true
}

Update current user

Updates details for the currently authenticated 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.

Request Body schema: application/json

Provided fields overwrite existing values on record associated with current user.

object (PutMeRequestUser)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "user": {
    },
  • "data_size_of_uploaded_attachments_and_folders": 0,
  • "data_size_limit": 0,
  • "data_size_limit_exceeded": true
}

Show a list of organisations the current user is an admin of

Show a list of organisations the current user is an admin of. Can take optional parameter tenant_id which restricts 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
{
  • "archived_orgs": [
    ],
  • "orgs": [
    ]
}

Create authentication request for user to authenticate using SIOP

This endpoint creates a athentication request for a user and return request_uri & short lived access token.

tenant_id can be passed as null and authentication flow will start against randomly picked tenancy user is a member of. After authentication is complete, GET /end_user/whoami endpoint can be used to find out which tenant you were authenticated against. A list of all tenants available to the user will be provided as well.

Request Body schema: application/json
did
required
string
tenant_id
string

Responses

Request samples

Content type
application/json
{
  • "did": "did:key:....",
  • "tenant_id": "986dcaf4-c1ea-4218-b6b4-e4fd95a3c28e"
}

Response samples

Content type
application/json
{
  • "uri": "openid://?request_uri=https://svx-api-dev.meeco.me/oidc/presentations/requests/3ce0ade6-01d4-4c3e-8726-e898d63f23eb/jwt",
  • "short_lived_access_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV..."
}

Process SIOP response id_token and generate access token for a User

This endpoint process SIOP athentication response id_token from a user and return access token.

Authorizations:
SVX-JWT
Request Body schema: application/json
required
object (IDPAuthorisationSiopSessionRequestDto)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
"string"

List invitations

Requires no security rights


Endpoint works for a tenant and organisation user based on the Meeco-Organisation-ID header.

Returns a list of invitations available to the caller.

In case of tenant context, endpoint returns all invitations available in the tenancy.

In case of organization context, endpoint returns all invitations available in the organisations.

Authorizations:
SVX-JWT
query Parameters
status
string
Example: status=pending

Filter invitation by status attribute: e.g. pending,expired.
Available values: pending, accepted, expired.
To filter by more than one status separate values by using comma.

invited_via
string
Enum: "email" "did"
Example: invited_via=email

Filter invitation by invited_via attribute. Possible values: email and did

order
string
Enum: "ASC" "DESC"
Example: order=DESC

order invitation, Default ordering: DESC (Supported: ASC, DESC)

order_by
string
Value: "given_name"
Example: order_by=given_name

order invitation for columnName, defaults column: created_at (Supported: given_name)

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Invite user to join the platform

Creates an invitation for user to join the platform. If user already exists, he/she will be added to the target organisation or tenant.

Payload example to invite an end user: (DEPRECATED: use /end_users/invitations API instead)

{ 
  "invitation": { 
    "via": "did" 
  } 
}

Tenant end user will be invited to is determined by the tid attribute value inside the JWT token.


Payload example to invite an admin:

{ 
  "invitation": { 
    "via": "email", 
    "email": "email@meeco.me", 
    "given_name": "Peter", 
    "family_name": "Peterson", 
  } 
}

Tenant admin will be invited to is determined by the tid attribute value inside the JWT token & empty the Meeco-Organisation-ID query param value in request.

Org admin will be invited to is determined by the tid attribute value inside the JWT token & Meeco-Organisation-ID query param value in request.

Global admin will be invited to is determined by the empty value in tid attribute value inside the JWT token & Meeco-Organisation-ID query param value in request.

The user who is sending the invitations can only invite other users within the tenant or organization they have selected.

For example, if the user is in the tenant context, they can only manage tenant users and invitations. Similarly, in the org context, they can only manage org users and invitations, and in the global context, they can only manage global users and invitations.

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (IDPCreateInvitationDto)

Responses

Request samples

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

Response samples

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

Exchange invitation token with a short lived access token Deprecated

Exchange invitation token for a short lived access token that allows Wallet to complete registration flow.

Short lived access token is valid for a minute and can be used to:

  • verify the request via POST /oidc/presentations/requests/verify
  • generate a verifiable presentation via POST /presentations/generate
  • generate an ID Token via POST /oidc/presentations/token
  • acccept an invitation and get a longer lasting access token to use in the joined tenancy via POST /invitations/{token}/accept

Request Body schema: application/json
required
object (IDPGenerateShortLivedAccessTokenDto)

Responses

Request samples

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

Response samples

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

Delete the invitation

Deletes a pending or expired invitation.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Fetch information about the invitation

Fetch information about the invitation.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Accept invitation by submitting presentation request response Deprecated

Accept invitation by submitting presentation request response. Works for invitation with invited_via attribute set to did.

If user is already a member of a tenant, invitation status will not change and only access token will returned.

Authorizations:
SVX-JWT
path Parameters
token
required
string
Request Body schema: application/json
id_token
required
string
vp_token
string
state
string

Responses

Request samples

Content type
application/json
{
  • "id_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "vp_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "state": "state-value"
}

Response samples

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

Resend invitation

Resend invitation email to the user.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Update a user detail

This endpoint updates a user detail

Authorizations:
SVX-JWT
Request Body schema: application/json
object (IDPUpdateUserPayloadDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

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

Change user password

This endpoint updates a user password

Authorizations:
SVX-JWT
Request Body schema: application/json
object (IDPUpdatePasswordPayloadDto)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Show info about the current user

Show information about the user with a valid JWT:

  • User ID from the JWT (taken from sub)
  • Tenant name
  • Whether the user is known to ATOM
Authorizations:
SVX-JWT

Responses

Response samples

Content type
application/json
{
  • "administered_archived_orgs": [
    ],
  • "administered_archived_tenants": [
    ],
  • "administered_orgs": [
    ],
  • "administered_tenants": [
    ],
  • "family_name": "string",
  • "given_name": "string",
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "tenant_in_jwt": {
    },
  • "user_known_to_atom": true,
  • "user_type": "string"
}

Verifiable Credentials

List available credential types

Requires no security rights


Endpoint works for a tenant and organisation user based on the Meeco-Organisation-ID header.

Returns a list of credential types available to the caller.

In case of tenant context, endpoint returns all credential types available in the tenancy.

In case of organization context, organizations list always contains only one item - caller organization ID.

Authorizations:
SVX-JWT
query Parameters
external_issuer_enabled
string
Example: external_issuer_enabled=false

To filter credential type by external_issuer.enabled flag

status
string
Enum: "all" "active" "archived"
Example: status=active

To filter archived credential types

order
string
Enum: "ASC" "DESC"
Example: order=DESC

Credential types response order. Default ordering: DESC (Supported: ASC, DESC)

order_by
string
Enum: "created_at" "name"
Example: order_by=created_at

Order credential types by an attribute, defaults to: created_at (Supported: name, created_at)

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

Content type
application/json
{
  • "credential_types": [
    ],
  • "organizations": [
    ],
  • "meta": {
    }
}

Create credential type

Requires the following security rights:

  • vc:tenant:manage

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCCreateCredentialTypeDto)

Responses

Request samples

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

Response samples

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

Fetch credential type detail

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Update credential type

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCUpdateCredentialTypeDto)

Responses

Request samples

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

Response samples

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

Archive credential type

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

restore credential type from archive

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Get a list of credentials organisation has issued

Requires the following security rights:

  • vc:org:manage

Lists credentials that selected organisation has issued.
Authorizations:
SVX-JWT
query Parameters
order
string
Enum: "ASC" "DESC"
Example: order=DESC

Credentials response order. Default ordering: DESC (Supported: ASC, DESC)

order_by
string
Value: "created_at"
Example: order_by=created_at

Order credentials by an attribute, defaults to: created_at (Supported: created_at)

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Generate credential based on type and claims provided

Requires the following security rights:

  • vc:org:manage

Generates unsigned verifiable credential token in JWT format. Client is expected to sign it with a private key.

An example of how credential signing in Javascript:

import { generateKeyPairFromSeed } from '@stablelib/ed25519'; 
import { EdDSASigner, hexToBytes } from 'did-jwt'; 

const key = generateKeyPairFromSeed(hexToBytes(SECRET_HEX)); 
const signerFn = EdDSASigner(key.secretKey); 

const signature = await signerFn(unsignedJwt); 
const vcJwt = [unsignedJwt, signature].join('.');

Issuer property caveat

We use openapi-generator to generate Typescript SDK for the given API swagger definition. However, openapi-generator does not support oneOf configuration properly and generates an invalid Typescript SDK. To avoid the problem, swagger defines issuer property only as string for the moment. While in fact, endpoint accepts issuer as an object in format of {id: string; name: string;} as well.


Type property caveat

Type is required for vc+sd-jwt format and must be a string
however, endpoint accepts Type as an Array of string for JWT VC in format of ["VerifiableCredential", "AlumniCredential"] as well.

Authorizations:
SVX-JWT
header Parameters
accept
string
Enum: "application/vc+sd-jwt" "application/jwt" "application/json"

When the "Accept" header is unspecified, the default format assumed for verifiable credentials is JWT.
This API supports the "application/vc+sd-jwt" media type for representing these credentials in JWT format and facilitates the creation of selectively disclosed verifiable credentials.

Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCGenerateCredentialDto)

Responses

Request samples

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

Response samples

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

Update credential status list entry

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
credential_id
required
string
required
object (VCUpdateCredentialStatusRequestStatusDto)

Responses

Request samples

Content type
application/json
{
  • "credential_id": "urn:uuid:23b841f2-a3dc-477f-a9e1-5024d1dcc02b",
  • "credential_status": {
    }
}

Response samples

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

Verify a VC/SDVC JWT

Verify a VC/SDVC JWT

Checks performed:

  • VC/SDVC format
  • VC/SDVC signature.
  • VC/SDVC expiration date is validated when the expirationDate attribute is present.
  • VC/SDVC issued at date is validated when the iat attribute is present.
  • The SDVC keyBindingJWT check is optional and is only performed if it is included in the SDJWT along with disclosures.
  • When keyBindingJWT is included in the SDJWT, the kb_audience and kb_nonce must be included in the verification options.
  • The SDVC also support URL instead of DID as issuer. URL will be used to construct .well-known endpoint to retrieve the public key.
  • Verifiable credential schema
  • Verifiable credential revocation list status and its validity

Credential expiration, schema and revocation status related checks are not considered critical and will be returned under warnings attribute. It is up for the client application to decide how these should be handled. All other failed checks will be served under errors attribute.

Verification options

You can optionally specify checks for the provided VC/SDVC JWT. If specified, only these checks will run.
By default, format, signature, expiration checks are mandatory and can not be taken out from checks list.
No further checks will be performed if JWT Token Format is invalid.

{ 
  "credential": { ... }, 
  "options": { 
      "checks": ["format", "signature", "expiration", "schema", "revocation_status"], 
      "kb_audience": "verifier DID or URL", 
      "kb_nounce": "nonce", 
  }, 
}

failed_to_verify_jwt error might appear in both: errors and warnings list.
In case of SD JWT VC it wraps any error that @meeco/sd-jwt-vc might throw.
In case of JWT VC it wraps any error that did-jwt-vc might throw.
So far, the only case when failed_to_verify_jwt appears in the warnings list is when credential is expired.

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCVerifySignedCredentialRequestDto)
object (VCCredentialVerificationOptionsRequestPayloadDto)

Responses

Request samples

Content type
application/json
{
  • "credential": {
    },
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "id": "urn:uuid:23b841f2-a3dc-477f-a9e1-5024d1dcc02b",
  • "checks": [
    ],
  • "warnings": [
    ],
  • "errors": [
    ]
}

Fetch information about a credential organistaion has issued

Requires the following security rights:

  • vc:org:manage

Fetch information about a credential organisation has issued by credential ID.
Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

List available schemas

Endpoint works for a tenant and organisation user based on the Meeco-Organisation-ID header.

Returns a list of schemas available to the caller.

In case of organization context, organization_ids list always contains only one item - caller organization ID.

Authorizations:
SVX-JWT
query Parameters
status
string
Enum: "all" "active" "archived"
Example: status=active

To filter archived schemas

order
string
Enum: "ASC" "DESC"
Example: order=DESC

Schemas response order. Default ordering: DESC (Supported: ASC, DESC)

order_by
string
Enum: "created_at" "name"
Example: order_by=created_at

Order schemas by an attribute, defaults to: created_at (Supported: name, created_at)

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Create schema

Requires the following security rights:

  • vc:tenant:manage

schema_json property must comply with specification.

Schema validity can be checked by using one of the Web (Online) validators listed at JSON schema specification site.

schema_json.$id attribute is not expected in the payload. API is going to assign its own internal version of it even if one is being passed.

Example (the most minimal set of attributes schema should contain):

{ 
  "$schema": "https://json-schema.org/draft/2019-09/schema", 
  "name": "Example name", 
  "description": "Example description", 
  "type": "object", 
  "properties": { 
    "id": { 
      "type": "string", 
    } 
  }, 
  "required": ["id"], 
  "additionalProperties": false, 
}
Authorizations:
SVX-JWT
Request Body schema: application/json
required
object (VCCreateSchemaDto)

Responses

Request samples

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

Response samples

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

Fetch schema detail

Endpoint works for a tenant and organisation user based on the Meeco-Organisation-ID header.

Returns schema information if caller has access to it.

In case of organization context, organization_ids list always contains only one item - caller organization ID.

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Update schema

Requires the following security rights:

  • vc:tenant:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
Request Body schema: application/json
required
object (VCUpdateSchemaDto)

Responses

Request samples

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

Response samples

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

Archive schema

Requires the following security rights:

  • vc:tenant:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

Restore schema

Requires the following security rights:

  • vc:tenant:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

Retrieve credential schema definition

Returns credential schema in a format described by specification.

path Parameters
id
required
string
version
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "981943a9-ed16-45fa-9138-31e6a75b4aee;version=1.0.0",
  • "type": "https://vc.meeco.me/schemas/basic/1.0.0/schema.json",
  • "version": "1.0.0",
  • "name": "aa4db41b-ddc7-4f58-b471-5acd36f363b6",
  • "author": "7262689e-1128-4f62-b491-e29673cc7be4",
  • "authored": null,
  • "schema": {
    }
}

Retrieve status list credential JWT

Returns status list credential in a format described by specification.

path Parameters
id
required
number

Responses

Response samples

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

Verifiable Presentations

JWT issuer discovery information

Returns JWT Issuer discovery information.

Response includes public keys in JWK format for token verification.

Responses

Response samples

Content type
application/json
{
  • "issuer": "https://issuer.url",
  • "jwks": {
    }
}

Get a list of Presentation Requests registered for organisation

Depending on the presence of the Meeco-Organisation-ID header, endpoint requires one of the following security rights:

  • vc:tenant:manage if Meeco-Organisation-ID is not specified
  • vc:org:manage if Meeco-Organisation-ID is specified

It gets registered Presentation Requests own by organisation
Authorizations:
SVX-JWT
query Parameters
status
string
Enum: "all" "active" "archived"
Example: status=active

To filter archived presentation requests

search
string

Search by name

order
string
Enum: "ASC" "DESC"
Example: order=DESC

Presentation requests response order. Default ordering: DESC (Supported: ASC, DESC)

order_by
string
Enum: "created_at" "name"
Example: order_by=created_at

Order presentation requests by an attribute, defaults to: created_at (Supported: name, created_at)

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Create a Presentation Request

Depending on the presence of the Meeco-Organisation-ID header, endpoint requires one of the following security rights:

  • vc:tenant:manage if Meeco-Organisation-ID is not specified
  • vc:org:manage if Meeco-Organisation-ID is specified

Register Presentation Request for organisation

When using a Presentation Definition with a format of vc+sd-jwt,the vp_formats of the Generated Presentation Request registration will be set to 

"vc+sd-jwt": { 
   "sd-jwt_alg_values": [ 
       "ES256", "EdDSA"  
     ], 
     "sd-jwt_alg_values": [ 
       "ES256", "EdDSA" 
     ] 
 } ,
and subject_syntax_types_supported will be set to urn:ietf:params:oauth:jwk-thumbprint.



"registration": { 
 ... 
 "subject_syntax_types_supported": [ 
    "urn:ietf:params:oauth:jwk-thumbprint" 
  ], 
  "vp_formats": { 
    "vc+sd-jwt": { 
     "sd-jwt_alg_values": [ 
        "ES256", "EdDSA" 
      ], 
     "sd-jwt_alg_values": [ 
        "ES256", "EdDSA" 
      ] 
    }, 
 ... 
}
Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCCreatePresentationRequestDto)

Responses

Request samples

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

Response samples

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

Verify a verifiable Presentation Request

Verify a Presentation Request

Checks performed:

  • Presentation Request signature
  • Presentation Request format and required attributes
  • Presentation Request expiration if present

failed_to_verify_jwt error might appear in both: errors and warnings list.
So far, the only case when failed_to_verify_jwt appears in the warnings list is when request is expired.

Authorizations:
SVX-JWT
Request Body schema: application/json
required
object (VCVerifyPresentationRequestDto)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": "038102ed-d224-4656-ae8d-10aeab5686aa",
  • "checks": [
    ],
  • "warnings": [
    ],
  • "errors": [
    ]
}

Get Presentation Request

Depending on the presence of the Meeco-Organisation-ID header, endpoint requires one of the following security rights:

  • vc:tenant:manage if Meeco-Organisation-ID is not specified
  • vc:org:manage if Meeco-Organisation-ID is specified

Get Presentation Request for organisation by ID
Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Update Presentation Request

Depending on the presence of the Meeco-Organisation-ID header, endpoint requires one of the following security rights:

  • vc:tenant:manage if Meeco-Organisation-ID is not specified
  • vc:org:manage if Meeco-Organisation-ID is specified

Update Presentation Request Archive status for organisation
Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCUpdatePresentationRequestDto)

Responses

Request samples

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

Response samples

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

Archive presentation requests

Depending on the presence of the Meeco-Organisation-ID header, endpoint requires one of the following security rights:

  • vc:tenant:manage if Meeco-Organisation-ID is not specified
  • vc:org:manage if Meeco-Organisation-ID is specified

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Get Presentation Request signed JWT representation

Get JWT represntation of Presentation Definition

path Parameters
id
required
string

Responses

Response samples

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

Restore presentation requests from archived

Depending on the presence of the Meeco-Organisation-ID header, endpoint requires one of the following security rights:

  • vc:tenant:manage if Meeco-Organisation-ID is not specified
  • vc:org:manage if Meeco-Organisation-ID is specified

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

List presentation request submissions

List presentation request submissions

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Present presentation request response

Present presentation request response

Authorizations:
SVX-JWT
path Parameters
id
required
string
Request Body schema: application/json
id_token
required
string
vp_token
string
state
string

Responses

Request samples

Content type
application/json
{
  • "id_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "vp_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "state": "state-value"
}

Response samples

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

delete presentation request submission

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
submission_id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Update presentation request submission

Update presentation request submission

Authorizations:
SVX-JWT
path Parameters
id
required
string
submission_id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCPresentationRequestUpdateSubmissionDto)

Responses

Request samples

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

Response samples

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

Verify a Presentation Request Submission

Requires the following security rights:

  • vc:org:manage

Verify a Presentation Request Submission

Checks performed:

  • Presentation Request Submission Presentation Request
  • Presentation Request Submission Id Token
  • Presentation Request Submission VP Token
  • Signature for all of the above
  • Format for all of the above
  • Expiration for all of the above
  • Revocation status for credentials within vp token
  • Presentation_definition uri match credential schema uri within vp token

Verification options

Certain set of checks is executed against each presentation request response attribute separately. Depending on the use-case some of those checks might not be necessary and could be disabled. To see the list of available check options - look at the schema of the verification options. If verification options were not provided all available checks will be executed.

Imagine expiration of the verifiable presentation is not relevant to our use-case. We can skip that check so no errors or wranings related to it would appear. Here is verification options payload example:

{ 
  "presentation_request_response": { ... }, 
  "options": { 
    "vp_token": { 
      "checks": ["format", "signature", "nonce"], 
    } 
  }, 
}

However, some of the checks are mandatory. If checks list includes format or signature option - it cannnot be taken out. Every other check is optional.

In case of id_token, failed_to_verify_jwt error might appear in both: errors and warnings list.
So far, the only case when failed_to_verify_jwt appears in the warnings list is when id_token is expired.

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCVerifyPresentationRequestResponseDto)
object (VCPresentationRequestResponseVerificationOptionsDto)

Responses

Request samples

Content type
application/json
{
  • "presentation_request_response": {},
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "checks": [
    ],
  • "warnings": [
    ],
  • "errors": [
    ],
  • "request": {
    },
  • "id_token": {
    },
  • "vp_token": {
    }
}

Generate id_token for presentation request submission

Requires no security rights


Generate id_token for request submission based on the Wallet information and the verifiable presentation token
Authorizations:
SVX-JWT
Request Body schema: application/json
request_uri
required
string
vp_token
string
issuer
string

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "state": "request-state",
  • "unsigned_id_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV...",
  • "vp_token": "eyJraWQiOiJkaWQ6aW9uOkVpQTZkWlV..."
}

Get a list of Presentation Definitions registered for organisation

Requires the following security rights:

  • vc:org:manage

It gets registered Presentation Definitions own by organisation
Authorizations:
SVX-JWT
query Parameters
status
string
Enum: "all" "active" "archived"
Example: status=active

To filter archived presentation definitions

search
string

Search by name

order
string
Enum: "ASC" "DESC"
Example: order=DESC

Presentation templates response order. Default ordering: DESC (Supported: ASC, DESC)

order_by
string
Enum: "created_at" "name"
Example: order_by=created_at

Order presentation templates by an attribute, defaults to: created_at (Supported: name, created_at)

per_page
any
Example: per_page=10

Number of records per page

page
any
Example: page=1

Page number (starting from 1)

header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Create a Presentation Definition

Requires the following security rights:

  • vc:org:manage

Register Presentation Definitions for organisation

When format of the Presentation Definition is set to vc+sd-jwt, then vp_formats of the Generated Presentation Request registration will be set to

     
    {
      "vc+sd-jwt": {
        "sd-jwt_alg_values": [
          "ES256", "EdDSA"
        ],
        "kb-jwt_alg_values": [
          "ES256", "EdDSA"
        ]
      }
    }

and subject_syntax_types_supported will be set to urn:ietf:params:oauth:jwk-thumbprint.


Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCCreatePresentationDefinitionDto)

Responses

Request samples

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

Response samples

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

Get Presentation Definition

Requires the following security rights:

  • vc:org:manage

Get Presentation Definition for organisation by ID
Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Archive presentation definition

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Get Presentation Definition JSON representation

Get JSON represntation of Presentation Definition

Authorizations:
SVX-JWT
path Parameters
id
required
string

Responses

Response samples

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

restore presentation definition from archive

Requires the following security rights:

  • vc:org:manage

Authorizations:
SVX-JWT
path Parameters
id
required
string
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Responses

Response samples

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

Generate verifiable presentation based on credentials provided

Requires no security rights


Generate verifiable presentation based on credentials provided

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCGeneratePresentationDto)

Responses

Request samples

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

Response samples

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

Verify a verifiable presentation

Requires the following security rights:

  • vc:org:manage

Verify a verifiable presentation

Checks performed:

  • Verifiable presentation signature
  • Verifiable presentation format and required attributes
  • Verifiable presentation expiration if present
  • Verifiable presentation credentials if present (check POST /credentials/verify for more information)

Presentation expiration check is not considered critical and will be returned under warnings attribute. It is up for the client application to decide how it should be handled. All other failed checks will be served under errors attribute.

failed_to_verify_jwt error might appear in both: errors and warnings list.
So far, the only case when failed_to_verify_jwt appears in the warnings list is when presentation is expired.

Authorizations:
SVX-JWT
header Parameters
Meeco-Organisation-ID
required
string

Specify Organisation ID to set request context to organisation

Request Body schema: application/json
required
object (VCVerifySignedPresentationRequestDto)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "checks": [
    ],
  • "warnings": [
    ],
  • "errors": [
    ],
  • "credentials": [
    ]
}