# What is the API-of-Me The getting started section is our primary source for people new to the platform. Everyone should be able to follow the [Quickstart](/latest/getting-started/quickstart) guide as it teaches the basics. Next step is to read the guides available in the ***Guides*** section and we highly recommend following along with the code samples that we provide. In the guides, some of the topics covered are * Introduction to the data model and terminology * Setting up a user with the necessary encryption artefacts * Creating an item and filling it with data * Learn the place of classifications in the system * Make a connection with another user and share an item Before diving in however, we'll start with an overview of the different components within Meeco. One more note, if you want to follow along, you'll want to sign up for the [free API keys](https://dev.meeco.me/signup). ## Platform Overview The Meeco platform or API-of-Me as we like to call it is a technology that is designed for everyone to store data and control how data is shared with or consent is given to other people or organizations that they trust. At no point is information stored or accessed in plaintext. It is only the client who can access this information inside a trusted execution environment. To enable this, Meeco provides a number of services that can be used in unison to provide a smooth experience. * **Vault** – securely store and share data from your vault. Manage connections and relationships to others. * **Keystore** – store and retrieve keys used in the different encryption tasks. * **Downloader** – facilitates downloading and sharing of attachments. Note that it is possible to pick and choose any of the solutions above if you happen to have a solution in place already. For example, the Vault can be used without the Keystore if you already have another key management component in place. ## **API Keys** All requests to the API must contain an API key, which you can request [for free](https://dev.meeco.me). ### **Environments** Currently, we have the following environments setup: * **sandbox**: allows you to experiment freely in an environment that is always updated to include the latest and the greatest endpoints and structures. ### **Services** Services can be reached by appending one of the following to `https://sandbox.meeco.me`: * `/vault`: Vault API * `/keystore`: Keystore API * `/downloader`: Download Engine API ### Tools Meeco has made available for use some tools to make using the API-of-Me easier. The Meeco CLI is available [here](https://github.com/Meeco/cli). Open the [Meeco CLI](/latest/tools/meeco-cli) section in this documentation for detailed installation instructions, and then you can get into the [Quickstart Guide](/latest/getting-started/quickstart) to create a User and an Item to save to your Vault. We've also created an encryption library called `Cryppo` that makes using the encryption and decryption routines we recommend much easier. We've created a Javascript and Ruby library - the examples contained within this guide will focus on the JS version. Check out `Cryppo-JS` [here](https://github.com/Meeco/cryppo-js) and `Cryppo` with Ruby [here](https://github.com/Meeco/cryppo). `cryppo-cli` is a tool that we've created that quickly makes you a Data Encryption Key, and let's you encode and decode information with it from the command line. We recommend using this to follow along with some of the examples on the site. You can even use them to generate encrypted data to use in the calls to the Developer Portal API Sandbox To read more about Cryppo and the Cryppo-CLI, open the Cryppo page in the Meeco Docs [here](/latest/tools/cryppo) # Setting Up ### Subscription Keys Firstly, a developer must sign up at the [Meeco Developer Portal](http://dev.meeco.me/). After following the signup procedure, confirming your account via an email and finally logging in, select "Get API Keys" from the home page. Give your subscription a name, read through and agree to the Terms of Use, and subscribe. This will generate the Primary and Secondary keys that are required to make requests in the developer portal. **Please note that the keys need to be approved by us, and therefore may not be ready for immediate use** The Primary key will be added to the `Meeco-Subscription-Key` header in all requests to the portal. Once the subscription keys have been activated, (you will receive an email telling you once it is active) you can begin to use them to make requests. Now, jump into the [Quickstart section](/latest/getting-started/quickstart) and follow along to create your first User and Vault item. # Quickstart This guide aims to get you up and running and familiar with the API in about 15 minutes. We'll teach you how to setup your first user and how to create your first item. ## Get the Meeco CLI Download the Meeco CLI and follow the installation instructions in the [Meeco CLI section](/latest/tools/meeco-cli) of the documentation. The first thing to do after setup is to create an `.environment.yaml` file that allows you to connect to the sandbox environment. {% code title=".environment.yaml" %} ```yaml vault: url: https://sandbox.meeco.me/vault subscription_key: DEV_PORTAL_SUBSCRIPTION_KEY keystore: url: https://sandbox.meeco.me/keystore subscription_key: DEV_PORTAL_SUBSCRIPTION_KEY ``` {% endcode %} ## Create a User Create your first user - let's call them "Alice". ```bash meeco users:create -p supersecretpassword > .alice.yaml ``` The command above does a lot, if you want to learn what happens behind the scenes look at the guide about [Setting up Access](https://github.com/Meeco/docs/blob/archive/2022-01/guides/setting-up-access.md). The end result is captured in a file `.alice.yaml` that holds the necessary information about the user that allows us to talk to the API in the next steps. In the next calls, you'll see an argument added with `-a .alice.yaml` ### Login as a User You can use the following command to login as the user you just created or if you are returning to a session. This command will re-create the tokens if they are expired. It outputs an Authorization config file for use with future commands. ```bash meeco users:login -a .alice.yaml ``` ### Get info about a User You can also get the information about a user by using the following command. This command will return the user's id and other user info like their dek. ```bash meeco users:get -a .alice.yaml ``` ## Creating an Item Items in the Meeco API require you to specify a template. This template can be seen as a contract with a number of predefined fields (which we call slots). To get all available templates execute the following command ```bash meeco templates:list -a .alice.yaml Fetching available templates... done kind: Templates spec: - passport_details - vehicle - bank_card - certificate_diploma - membership_subscription - pet - device - password - important_document - travel - services - medical - custom ``` Let's create a `vehicle` item. To prepare this we can run the create config command First, let's have a look at what kind of information the template holds. ```bash meeco templates:info vehicle -a .alice.yaml Fetching template 'vehicle'... done kind: Template spec: id: 0c385f1d-8825-4932-a6ab-846178b816e4 name: vehicle description: null ordinal: 1 visible: true user_id: null updated_at: 2020-09-10T14:13:12.029Z image: https://sandbox.meeco.me/vault/images/ff1c25e9-530a-4103-b649-986631bcb448 classification_node_ids: - 8670d4c6-8d68-49a4-bd21-0fc8cefa705d slot_ids: [] label: Vehicle background_color: null slots: [] ``` Then, create the config file: ```bash meeco items:create-config vehicle -a .alice.yaml > .item-config.yaml ``` The next step is to edit the file to contain some data. {% code title="vehicle.yml" %} ```bash kind: Item metadata: template_name: vehicle spec: label: "DeLorean" slots: - name: purchase_date value: "01/01/1981" - name: type value: "Sports Car" - name: vin value: "123456789" - name: licence_plate value: "1AAA999" - name: model_make value: "DMC DeLorean" - name: power value: "132 PS" ``` {% endcode %} Based on this configuration, we can create a new vehicle in Alice's digital vault. ```bash meeco items:create -i .item-config.yaml -a .alice.yaml > .item.yaml ``` Congratulations, you have now created your first item in the ***Vault***. From here you can either keep learning about the Meeco Platform and tools, or jump into the [Connections and Sharing tutorial](https://github.com/Meeco/docs/blob/archive/2022-01/guides/connections-and-sharing.md) to keep using the CLI to make a connection with another user and share the item you created above. # Terminology ## Classification A ***Classification*** is a link between a [Classification Node](#classification-node) and a classified entity. [Items](#item), [Slots](#slot) and [Templates](#item-template) can have Classifications. ## Classification Node A [Classification Scheme](#classification-scheme) consists of a tree of ***Classification Nodes***. A Classification Node * belongs to a Classification Scheme * has a parent Classification Node, unless it is the root node * has property `name` * has property `label` * has property `description` * has property `image` ## Classification Scheme The Meeco platform has a very flexible way to tag information. Instead of having a flat list of tags the system can be configured to have multiple independent [Classifications](#classification). Combinations of these Classifications are called ***Classification Schemes***. ## Connection A ***Connection*** between two users is a channel via which users can share [Items](#item). It is essentially a pair of [public keys](#keypair) (yours and the other party's), and user ids. You can read a more detailed explanation of Sharing Items [here](https://github.com/Meeco/docs/blob/archive/2022-01/concepts/connections-and-sharing.md), and you can run through creating a Connection and sharing an item using the Meeco CLI tool [here](https://github.com/Meeco/docs/blob/archive/2022-01/concepts/connections-and-sharing.md). (Make sure you've gone through the [Quickstart guide](/latest/getting-started/quickstart) first to have gained access to the API sandbox!) ## Data Encryption Key (DEK) ***Data Encryption Keys*** are [`AES256-GCM`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) keys used to encrypted and decrypt user data. Data Encryption Keys are stored in the [Keystore](#keystore) encrypted with the Key Encryption Key. It is possible for a user to have multiple Data Encryption Keys: there is one that is used to encrypt your private data; new Keys are created for any Shares, so that other users never see your private DEK. ## Item An ***Item*** is a group of [Slots](#slot) related by a topic. For example, a user profile is an Item. A club membership, a flight reservation - all these can be Items, each having a number of Slots of different types in them. The Slots in an Item are keyed by their name property, so an Item can be thought of like a dictionary or hash-map containing only encrypted values. If a user makes a [Connection](#connection) with another user, they can share the encrypted slots with that user. ## Item Template An ***Item Template*** is a predefined list of empty [Slots](#slot). Each \[Item]\(]\(#item) is created by cloning such a template and filling in the Slots with your data. You can read a more detailed document about Items and Templates [here](https://github.com/Meeco/docs/blob/archive/2022-01/concepts/items-and-slots.md) ## Key Encryption Key (KEK) The ***Key Encryption Key*** is used to encrypt all other keys (data encryption keys and keypairs) before they are stored in the [Keystore](#keystore). The Key Encryption Key is encrypted with the [Passphrase Derived Key](#passphrase-derived-key-and-derivation-artefacts), which is private to the user. In the current implementation this is an [`AES256-GCM`](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) key, but the serialization format of encrypted data used in the Meeco platform allows for adding new encryption algorithms without breaking backwards compatibility. There is one Key Encryption Key per user. ## Keypair Public key cryptography is used for exchanging [DEKs](#data-encryption-key-dek) when [Connections](#connection) are created between users. Private keys are stored in the [Keystore](#keystore) encrypted with the [Key Encryption Key](#key-encryption-key-key). ## Keystore Storage for secrets and keys. This is where the [Data Encryption Keys](#data-encryption-key-dek), [Public/Private Key pairs](#keypair), and the [Key Encryption Key](#key-encryption-key-kek), are stored along with the [Derivation Artefacts](#passphrase-derived-key-and-derivation-artefacts). All of the stored keys are encrypted with the KEK, except for KEK itself, which is encrypted with the Passphrase Derived Key. No encryption is done in the Keystore, the Cryppo library is required to create and use keys. In the [Meeco Developer Portal](https://dev.meeco.me) the Keystore is reachable through the `https://sandbox.meeco.me/keystore` endpoint. ## Passphrase Derived Key And Derivation Artefacts A ***Passphrase Derived Key*** is a [`PBKDF2`](https://en.wikipedia.org/wiki/PBKDF2) key. To generate or re-generate this key, a passphrase and derivation artefacts are required. Derivation artefacts include: * Number of iterations * Salt * Derived key length In the current iteration of our [*Secret Key*](#secret-key) authentication and passphrase derivation the number of keys `Number of iterations` and `Derived key length` are static and the Salt is pulled from the Secret Key. Derivation artefacts are stored in the [Keystore](#keystore). Neither the Passphrase Derived Key itself nor the passphrase are stored in the Keystore. ## Secret Key The secret key is a component of the authentication flow. The format for version 1 is as follows: ```bash {version}-{username}-{salt} ``` * The `username` is generated by the server * The `salt` is a 256 bit randomly generated key, which is base58 encoded and has a hypen (`-`) at each 6th character. The salt component created on the client and stored (securely) by the user. It is used to generate 1. an encryption key ([PDK](#passphrase-derived-key-and-derivation-artefacts)) with which to encrypt your [Key Encryption Key (KEK)](#key-encryption-key-kek). 2. a password which, along with a username, will be used for [Secure Remote Password (SRP)](#srp---secure-remote-password) authentication. ## Share A ***Share*** is created when a user grants access to their [Item](#item) to another user that they've [Connected](#connection) with. The Item is re-encrypted with a [data encryption key](#data-encryption-key-dek) shared with the recipient of the Share. An Item you have received via a Share, can be shared to another user, but you cannot alter any of its Slots. Only the original creator of the Item can update the Share, other than deleting it. For a detailed look at Sharing and Connections, have a look at the Connections and Sharing Guide, or read through the tutorial for creating a Connection and sharing an item using the [Meeco CLI](/latest/tools/meeco-cli) tool [here](https://github.com/Meeco/docs/blob/archive/2022-01/concepts/connections-and-sharing.md) ## Slot A ***Slot*** in the smallest data entity in the [Vault](#vault). An [Item](#item) is made up of Slots, which are keyed by their `name` property. Each Slot has a `name`, a `label`, and a `value`. Note that the API does not *return* the `value` property, but `encrypted_value`. The API will not allow storing any unencrypted data in either `value` or `encrypted_value`. Slot values are always stored in an encrypted form and only the user can decrypt and read them. Once encrypted and serialized - you can use one of Meeco's [Cryppo](/latest/tools/cryppo) family of encryption libraries - a Slot value of "BMW" would look something like this: ```bash "encrypted_value": "Aes256Gcm.2hDl.LS0tCml2OiAhYmluYXJ5IHwtCiAgQWQwSThDZk5qRnFycmFuMAphdDogIWJpbmFyeSB8LQogIDJXVklzbUxOSWVoOHZIVDB1ZzBtZVE9PQphZDogbm9uQQo=" ``` Slots are typed, however the values cannot be checked that they match the given type, as the API does not have decrypted keys for these items. Example Slot types are: * `key_value` * `bool` * `date` * `datetime` * `image` * `url` * `phone_number` * `email` * `password` * `attachment` Notice that new types cannot be created; `key_value` should be the default type used. Slots are able to be shared after two users have made a [Connection](#connection) with each other. ## SRP - Secure Remote Password An authentication method which sends proof that a user knows their password without revealing the actual password to the server. You can read more about it here - ## Vault The Vault is where a User of the API-of-Me will store and share the [Items](#item) they create. The user's data is end-to-end encrypted, this means that the users data cannot be decrypted and read by anyone at Meeco. Your data is *your* data. In the [Meeco Developer Portal](https://dev.meeco.me) the Vault is reachable through the `https://sandbox.meeco.me/vault` endpoint. # Secure Value Exchange The platform consists of the following components. * Vault * Keys * Exchange * Consent * Events * Wallet * Credentials * Tenant & Organisation Management The following sections explain each component. # Vault # Enterprise Vault An Enterprise Vault is a secure service like an end-user Vault with added functionalities tailored to enterprises. Enterprise refers to any entity, for example a company, a government, or a club. The term “Organisation” is used as the entity that controls the Enterprise Vault. ## Functionalities The key functionalities of an Enterprise Vault are as follows: * Items, Slots, Connections, Sharing, Classifications, Attachments as per an end-user Vault. * The Organisation that manages an Enterprise Vault can have one or more Administrators (Admins), who are authorised to invite and manage other Admins and deploy Services. The (Organisation) Admins and Services all have access to Items in the Enterprise Vault. * Admins can be assigned fine grained permissions (see ATOM > Security Rights), in line with the roles within the authorised Organisation, to allow different access rights to Items within the Vault. * An Organisation can connect to any user or other organisation Vaults to provide services. * Fined-grained consent to manage the sharing of data with end users. * The Organisation Admin also has the ability to on-board third-party services, associated with the Organisation, to act on behalf of that Organisation and access Items, Connections and Shares in the Enterprise Vault. ## Services Typical Services that are executed on behalf of an Enterprise Vault are: Storing sensitive personal data that needs to be shared with other users. For example, verifiable credentials that are issued, or receiving verifiable credentials for verification purposes. Securely sharing (structured) data in a persistent or one-off way. This data can be plain text, a document (e.g. verifiable credential) or an attachment (e.g. pdf). A specific implementation is the creation of an Item pushed via a secure API to an end-user Vault, without storing the item in the Enterprise Vault. This allows the secure sharing of sensitive data from other systems without the need to maintain the Item in the Enterprise Vault. Securely receiving (structured) data from any authorised party (end-user or third party) within an Enterprise Vault ecosystem. This enables easy integrations with other services ## Management of the Enterprise Vault An Enterprise Vault is managed via: **Enterprise Portal** – The Enterprise Portal is an application that enables Organisation Admins to login and create other Admins, Item Schemas and Items, along with viewing Items created by the Organisation. It also provides a view of the end-users and other third-party services the Organisation is connected to, including the outgoing and incoming shares to and from these these parties. **API** – All functionality is available using the SVX API to connect services. **CLI** – Command line interface to interact with the Enterprise Vault. # Credential Schemas Credential schemas are used to define the structure for the claims of a verifiable credential. It uses the [Data Schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property of a credential. Schemas use the [Verifiable Credentials JSON Schema 2022](https://w3c-ccg.github.io/vc-json-schemas/) specification, published by the W3C Credentials WG. Using schemas allows tenants, organisations and users to * Agree on the structure of data and facilitate data exchange * Extract information from the schema It is possible to create a credential without specifying a schema via the API, but the Enterprise Portal makes this step mandatory. In the portal, the schema is used to render an input form when creating a credential via the UI. A credential schema, once published, is versioned and made available via a public URL. This allows anyone to validate it at any point in time. ## Prerequisites * Verifiable Credential JSON Schema ### Verifiable Credential JSON Schema Each JSON Schema consists of the following mandatory attributes: * type (e.g. JsonSchemaValidator2018). The specific type definition determines the content of each data schema. * id (a URI that identifies the schema file) Credential schema upload is available to Tenant Administrators and must comply with the following rules: * A plain JSON object. * The structure is later checked based on the specification: JSON Schema All the attributes in the example are required, but values could be different, e.g. URL address of Schema, name, description etc. Below is an example JSON schema. ```bash { "$schema": "https://json-schema.org/draft/2019-09/schema", "name": "Example", "description": "Example", "type": "object", "properties": { "id": { "type": "string", } }, "required": ["id"], "additionalProperties": false, } ``` ## Who can use this? Credential schemas are managed by a tenant administrator. They assign it to an organisation. An organisation can list the credential schemas that are assigned to them. Anyone can read the JSON schema (via a separate endpoint) that is part of the credential schema object. ## Create Credential Schema Creation of a credential schema. **Endpoint** ```bash POST /schemas ``` **Request** * Name – name of the credential schema * JSON Schema - JSON schema file * List of organisations - organisations where this credential schema can be used (optional) **Responses** The credential schema object that is created. Upon creation, version `1.0` is assigned. ## Read Credential Schemas Retrieve a list of credential schemas. **Request** ```bash GET /schemas ``` **Request** * Organisation (header) **Responses** List of credential schema objects available to the user. In the context of an organisation, the `organization_ids` attribute contains only one item - caller organisation ID. ## Update Credential Schema Update an existing credential schema by ID. Note that in this version, the schema cannot be updated. **Endpoint:** ```bash PUT /schemas/{id} ``` **Request** * ID of Credential Schema * Name – name of the credential schema * List of organisations - organisations where this credential schema can be used (optional) **Responses** The updated credential schema object. ## Read Verifiable Credential JSON Schema Public endpoint that returns the JSON schema file. No authentication necessary. **Endpoint** ```bash GET /schemas/{id}/{version}/schema.json ``` **Request** * Id – ID of the Credential Schema * Version – Version of the Credential Schema **Responses** Returns JSON schema for a credential schema # Credential Types Credential types are used to link a [Credential Schema](/latest/guides/credential-schemas) to an Organisation and define the visual appearance for a credential issued by that organisation. The credential type is used in the Meeco Portal and Meeco Wallet to give a credential of that particular schema and that particlar organisation its unique look and feel. ## Prerequisites * [Credential Schema](/latest/guides/credential-schemas) ## Who can use this? Credential types are managed by an organisation administrator. ## Create Credential Type Creation of a credential type. **Endpoint** ```bash POST /credential_types ``` **Request** * Name – name of the credential type * Credential Schema - credential schema this type is applicable for * Style * Text Colour * Background Colour – Background colour for the credential (CSS styles supported) * Logo – Logo displayed in the top left corner of the credential **Responses** The credential type object that is created. # Credentials # Issue Credentials Issue credential is the first operation in the lifecycle of a [Verifiable Credential](https://www.w3.org/TR/vc-data-model/#lifecycle-details). It assists the Issuer in creating the credential so it can be delivered to the subject of the credential. The supported modes are: * Generating credential – generates an (unsigned) credential that requires signing. * Issuing credential – credential is generated and signed with keys managed on the platform. The response is a JSON formatted verifiable credential with a system-generated unique id and issuance date. ## Prerequisites * [Credential Schema](/latest/guides/credential-schemas) – [data schema](https://www.w3.org/TR/vc-data-model/#data-schemas) of the credential * [Credential Type](/latest/guides/credential-types) * [DID](/latest/guides/dids/did-methods) ## Who can use this? An onboarded organisation in the tenacy set up as issuer by the tenant. ## Generate a Credential Generating a credential requires issuance data and data related to the subject. This data is structured following the datamodel of [W3C Verifiable Credential Core Data Model](https://www.w3.org/TR/vc-data-model/#core-data-model) and following the structure of the chosen credential schema. The endpoint resolves the DIDs and performs a number of coherency checks. The result is a JWT ready to be signed. **Endpoint** ```bash POST /credentials/generate ``` **Request** * [Credential Type](https://github.com/Meeco/docs/blob/archive/2022-01/guides/credentials/credential-types.md) * Issuer * DID – fully qualified DID string * Name – Name of the issuer (optional) * Claims – maps to the `credentialSubject` attribute of a credential * Subject DID – typically, the `id` property contains the DID of the subject * Expiration date – datetime after which the credential expires * Revocable – if true, the generated credential can be revoked later on. **Responses** The credential object that is generated. This contains * ID of the credential * Unsigned credential in `vc-jwt` data format * Meta data ## Issue a Credential [Generate](#generate-credential) and sign a credential for the given issuer. The result is a signed vc-jwt. To sign the credential, a fully qualified DID string or object with `id` property needs to be provided. The DID and its verification keypair needs to be under control of the platform to be able to perform the signing. **Endpoint** ```bash POST /credentials/issue ``` **Request** * [Credential Type](https://github.com/Meeco/docs/blob/archive/2022-01/guides/credentials/credential-types.md) * Issuer * DID – fully qualified DID string * Name – Name of the issuer (optional) * Claims * Subject DID – typically, the `id` property contains the DID of the subject * Expiration date – datetime after which the credential expires * Revocable – if true, the generated credential can be revoked later on. **Responses** The credential object that is generated. This contains * ID of the credential * Signed Credential in `vc-jwt` data format * Meta data # DIDs # DID Resolver Resolving & dereferencing supported DID methods ### DID Resolution DID resolution, also referred to as the "Read" operation, is a function that takes a DID (and some metadata) as input and returns a DID document (and some metadata) as output. Resolution is performed as defined in the [DID Core](https://www.w3.org/TR/did-core/) and [DID Resolution](https://w3c-ccg.github.io/did-resolution/) specifications. The implementation is based on the [Universal Resolver](https://github.com/decentralized-identity/universal-resolver) project. Supported output is * DID document and metadata in JSON-LD * DID document in JSON-LD * DID document in CBOR ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw" ``` ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -H "Accept: application/did+ld+json" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw" ``` ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -H "Accept: application/did+cbor" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw" ``` ### DID URL Dereferencing DID URL dereferencing is a function that takes a DID url as input and returns either (1) a DID document, (2) a resource within the DID document or (3) a resource external to the DID document. Using a fragment to fetch ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -H "Accept: application/did+ld+json" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw#key1" ``` # DID Registrar Creating, updating & deactivating supported DID methods DID registration covers the three operations that modify a DID, namely "Create", "Update" and "Deactivate". It takes a DID and (often) a DID document as input to perform the requested operation. Registration is performed as defined in the [DID Core](https://www.w3.org/TR/did-core/) and [DID Registration](https://w3c-ccg.github.io/did-resolution/) (draft) specifications. The implementation is based on the [Universal Registrar](https://github.com/decentralized-identity/universal-registrar) project. # DID Methods Platform supports the following DID Methods | Method | Description | Specification | Resolver | Registrar | | ---------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------- | --------- | | `did:ebsi` | DIDs on the EBSI network from the European Blockain Initiative | [EBSI DID Method](https://ec.europa.eu/digital-building-blocks/wikis/display/EBSIDOC/EBSI+DID+Method#) | yes | yes | | `did:indy` | DIDs on Hypledger Indy from Sovrin Foundation | [Indy DID Method](https://hyperledger.github.io/indy-did-method/) | yes | yes | | `did:key` | Simples possible implementation of a DID method based on public/private key pairs. Registry independent. | [Key DID Method](https://w3c-ccg.github.io/did-method-key/) | yes | yes | | `did:web` | DIDs on web server infrastructure | [Web DID Method](https://github.com/w3c-ccg/did-method-web) | yes | yes | We're working on adding support for the following | Method | Description | Specification | Resolver | Registrar | | ------------ | --------------------------------------------- | ---------------------------------------------------- | -------- | --------- | | `did:hedera` | DIDs on Hedera Hashgraph from Hbar Foundation | [Hedera DID Method](/latest/guides/dids/did-methods) | yes | yes | Don't find your preferred DID method in the list? Contact us! # did:key This page describes how to perform the following operations for `did:key` using the SVX platform. * Resolve * Create ### Resolve ```bash curl -H "Authorization: Bearer TOKEN" \ -H 'accept: application/ld+json;profile="https://w3id.org/did-resolution"' \ -X GET "https://svx-api.meeco.me/did/{did:key identifier}" ``` ### Create #### Generate Keypair [Create your DID controller keypair](/latest/guides/dids/did-controller-keypair) Encode the public key using Base64 URL encoding. ```bash cat pubkey | tail -c +13 | basenc --base64url # e.g. YeAEwLNEJfHRVMSOs-Fr0C5mW9OFt3GACXtM5A7q7fo= ``` #### Create DID Call DID Create API to create the new DID and return the associated DID document. Use the Base64URL representation of the public key from previous step. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://svx-api.meeco.me/did/create?method=key" \ -H "Content-Type: application/json" \ -d '{ "options": { "clientSecretMode": true }, "secret": { }, "didDocument": { "@context": ["https//www.w3.org/ns/did/v1"], "verificationMethod": [{ "id": "#temp", "type": "JsonWebKey2020", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "{Replace_With_Above_Generated_Base64URL_String}" } }] } }' # e.g. # { # "jobId": null, # "didState": { # "did": "did:key:z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV", # "state": "finished", # "secret": { # "verificationMethod": [ # [ # { # "id": "#temp", # "purpose": [ # "authentication" # ] # }, # { # "id": "did:key:z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV#z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV", # "controller": "did:key:z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV", # "purpose": [ # "authentication", # "assertionMethod", # "capabilityInvocation", # "capabilityDelegation", # "keyAgreement" # ] # } # ] # ] # } # }, # "didRegistrationMetadata": { # "duration": 65, # "method": "key" # }, # "didDocumentMetadata": null # } ``` # did:web This page describes how to perform the following operations for `did:web` using the SVX platform. * Resolve * Create * Update * Deactivate ### Resolve ```bash curl -H "Authorization: Bearer TOKEN" \ -H 'accept: application/ld+json;profile="https://w3id.org/did-resolution"' \ -X GET "https://svx-api.meeco.me/did/{did:web identifier}" ``` ### Create #### Generate Keypair [Create your DID controller keypair](/latest/guides/dids/did-controller-keypair) Encode the public key using Base64 URL encoding. ```bash cat pubkey | tail -c +13 | base58 # e.g. 7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7 ``` **Create DID** Call the DID Create API to create a new `did:web` and return the associated DID document. Use the Base58 representation of the public key from previous step. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://svx-api.meeco.me/did/create?method=web" \ -H "Content-Type: application/json" \ -d '{ "options": { "clientSecretMode": false }, "didDocument": { "verificationMethod": [ { "id": "did:web:did-web.meeco.me:{Replace_With_Above_Generated_Base58_String}#key-1", "type": "Ed25519VerificationKey2018", "publicKeyBase58": "{Replace_With_Above_Generated_Base58_String}" } ], "service": [ { "type": "LinkedDomains", "serviceEndpoint": "meeco.me" } ], "authentication": [ "did:web:did-web.meeco.me:{Replace_With_Above_Generated_Base58_String}#key-1" ], "assertionMethod": [ "did:web:did-web.meeco.me:{Replace_With_Above_Generated_Base58_String}#key-1" ] } }' # e.g. # { # "jobId": null, # "didState": { # "state": "finished", # "secret": null, # "didDocument": { # "verificationMethod": [ # { # "id": "did:web:did-web.meeco.# me:7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7#key-1", # "type": "Ed25519VerificationKey2018", # "publicKeyBase58": "7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7" # } # ], # "service": [ # { # "type": "LinkedDomains", # "serviceEndpoint": "meeco.me" # } # ], # "authentication": [ # "did:web:did-web.meeco.me:7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7#key-1" # ], # "assertionMethod": [ # "did:web:did-web.meeco.me:7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7#key-1" # ], # "id": "did:web:did-web.meeco.me:b4c63177-1ba3-48d2-8297-447c843db3d7" # }, # "did": "did:web:did-web.meeco.me:b4c63177-1ba3-48d2-8297-447c843db3d7" # }, # "didRegistrationMetadata": { # "duration": 175, # "method": "web" # }, # "didDocumentMetadata": {} # } ``` ### Update Call the DID Update API to update an existing `did:web` and return the associated DID document. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://identity-network-dev.meeco.me/did/update?method=web" \ -H "Content-Type: application/json" \ -d '{ "did": "{Replace_With_DID_WEB_Identifier}", "didDocumentOperation": [ "setDidDocument" ], "options": { "clientSecretMode": false }, "didDocument": { "id": "{Replace_With_DID_WEB_Identifier}", "verificationMethod": [ { "id": "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1", "type": "Ed25519VerificationKey2018", "publicKeyBase58": "Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE" } ], "service": [ { "type": "LinkedDomains", "serviceEndpoint": "updated.example.com" } ], "authentication": [ "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" ], "assertionMethod": [ "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" ] } }' # e.g. # { # "jobId": null, # "didState": { # "state": "finished", # "didDocument": { # "id": "did:web:did-web.meeco.me:b4c63177-1ba3-48d2-8297-447c843db3d7", # "verificationMethod": [ # { # "id": "did:web:did-web.meeco.# me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1", # "type": "Ed25519VerificationKey2018", # "publicKeyBase58": "Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE" # } # ], # "service": [ # { # "type": "LinkedDomains", # "serviceEndpoint": "updated.example.com" # } # ], # "authentication": [ # "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" # ], # "assertionMethod": [ # "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" # ] # } # }, # "didRegistrationMetadata": { # "duration": 111, # "method": "web" # }, # "didDocumentMetadata": {} # } ``` ### Deactivate Call DID Deactivate API to deactivate an existing `did:web`. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://identity-network-dev.meeco.me/did/deactivate?method=web" \ -H "Content-Type: application/json" \ -d '{ "did": "{Replace_With_DID_WEB_Identifier}", "options": { "clientSecretMode": false } }' ``` # did:ebsi Working on it. If you need documentation urgently, don't hesitate to reach out to us via the website. # did:indy Working on it. If you need documentation urgently, don't hesitate to reach out to us via the website. # DID Controller Keypair Creating a keypair used to control a DID method Create a new DID controller keypair using openssl. In this example, we use Ed25519, but other algorithms are also supported (see specification). {% hint style="info" %} Make sure you have openssl & GNU coreutils installed and avalible on command line (e.g. `brew install coreutils` on macOS) {% endhint %} ```bash openssl genpkey -algorithm ed25519 -outform DER >privkey openssl pkey -in privkey -pubout -out pubkey -inform DER -outform DER ``` This creates two files, `pubkey` and `privkey`. Depending on the method, the public key is encoded in either * Base64 URL (`base64url`) * Base58 (`base58`) ### FAQ #### How do I install `base58` app (on macOS). There are two ways to install it. If one app doesn't work, try the other one. ```bash # using howbrew brew install base58 # using cargo (requires rust tooling to be installed) cargo install bs58-cli ## hint latter works best by symlinking: ln -s source_path target_in_path/base58 ``` #### How to install & use `openssl 3` (on macOS). Some newer features are only available in the latest version of openssl, version 3. To install it ```bash brew install openssl@3 ``` It is not automatically added to the path as macOS uses LibreSSL. Therefore you can use the absolute path. ``` /opt/homebrew/opt/openssl@3/bin/openssl ``` # OpenID Connect # For Verifiable Presentation List of endpoints that assist holder wallet and verifier to participate in the [OpenID for Verifiable Presentations](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) protocol. Built on top of OAuth 2.0, it allows a client (wallet) to present claims in the form of [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/). Currently, credentials and presentations in JWT format (vc-jwt, vp-jwt) are supported. The endpoints provided are to support the following high-level verification flow. {% @mermaid/diagram content="sequenceDiagram autonumber participant H as End User participant W as Wallet/SIOP participant V as Verifier/RP V->>V: Create Request object V->>V: Generates and displays
QR Code with `request_uri` H-->>W: Opens app W-->>V: Scans QR Code W->>W: Obtains `request_uri`
from QR Code W->>V: Retrieve Request object
(signed JWT) W->>W: Verify Request W->>W: Identify VCs required
in the Request object W->>W: Generates a VP W->>W: Create Response object W->>V: Post Response to /redirect\_uri V->>V: Verify Response V-->>W: Acknowledgement" %} The flow centers around the creation and exchange of a Request and a Response object, by the verifier and holder (wallet) respectively. The endpoints are categorised under these two headings. ## Prerequisites * [DID](https://github.com/Meeco/docs/blob/archive/2022-01/guides/oidc/dids/did-methods.md) * [Presentation](/latest/guides/presentations) ## Who can use this? Used by organisations (verifiers) and users (holders) in a verification flow using the OpenID Connect protocol. ## Request List of endpoints to help create and verify the [Request](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-request) part of the verification flow. ### Create Presentation Requests Creation of a presentation request. **Endpoint** ```bash POST /oidc/presentations/requests ``` **Request** * Organisation (header, optional) * Name – title string * Description – explains the purpose for which the request is created * Verifier * [DID](/latest/guides/dids/did-methods) * Name * Expiration Date – timestamp the request token expires * Redirect Base URI * [Presentation Definition](/latest/guides/presentation-definitions) **Responses** The presentation request object that includes an unsigned JWT. The client calling this endpoint (e.g. verifier system) is responsible for adding the signature. ### Update Presentation Request Update an existing presentation request by ID. One of the options is to use the platform to host the (signed) request (see [here](#read-presentation-request-jwt)). The request parameters itself can't be updated, only the signed request JWT. **Endpoint** ```bash PUT /oidc/presentations/requests/{id} ``` **Request** * Request ID * Organisation (header, optional) * Signed request JWT **Responses** The updated presentation request object. ### Read Presentation Request JWT Public endpoint that returns the (signed) presentation request JWT. **Endpoint** ```bash GET /oidc/presentations/requests/{id}/jwt ``` **Request** * Request ID **Responses** Signed presentation request JWT token. ### Verify Presentation Request Verification of the SIOP token. The steps performed during this verification are: * Resolve verifier DID * Verify request signature * Extract the presentation definition uri * Verify presentation definition structure **Endpoint** ```bash POST /oidc/presentations/requests/verify ``` **Request** * Signed presentation request JWT **Responses** The result of the verification, either true or false. ## Response List of endpoints to help create and verify the [Response](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-response) part of the verification flow. ### Create Presentation Response Generate id\_token for request submission based on the Wallet information and the verifiable presentation token **Endpoint** ```bash POST /oidc/presentations/token ``` **Request** * Presentation Request JWT **Responses** The presentation response object that includes two unsigned JWT, `id_token` and `vp_token`. The client calling this endpoint (e.g. holder wallet) is responsible for adding the signatures for each token. ### Verify Presentation Response Verify the presentation response to a given request. The steps performed are: * Verify ID Token * Verify VP Token * [Verify presentation](/latest/guides/presentations) * Verify if the response is valid for the given request, i.e. if it matches the presentation definition from the request **Endpoint** ```bash POST /oidc/presentations/response/verify ``` **Request** * Presentation Request JWT * Signed ID Token * Signed VP Token **Responses** The result of the verification, either true or false. In case of false, all errors are provided, with an explanation. # Presentations Presentation, short for [Verifiable Presentation](https://www.w3.org/TR/vc-data-model/#presentations), is a data model that allows a holder of [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#credentials) to present them in a way that that the Verifier can attest the authorship of the credentials included. The data format used for the presentation is [vp-jwt](https://www.w3.org/TR/vc-data-model/#json-web-token). Other formats are not supported at this time. ## Prerequisites * [DID](/latest/guides/dids/did-methods) * Credentials ## Who can use this? Presentations are generated by the holder and verified by an organisation or another user. ## Generate Verifiable Presentation Generate a verifiable presentation, ready for signing. **Endpoint** ```bash POST /presentation/generate ``` **Request** * DID * List of VCs **Responses** The presentation object that includes an unsigned JWT. The client calling this endpoint (e.g. holder wallet) is responsible for adding the signature. ## Verify Verifiable Presentation Verify a given verifiable presentation. The steps performed during this verification are * Validate the presentation structure * Resolve the presentation DID * Verify the presentation signature * For each credential in the presentation * Validate the credential structure * Resolve the issuer DID * Verify the credential signature **Endpoint** ```bash POST /presentation/verify ``` **Request** * Verifiable Presentation – supported format is vp-jwt **Responses** The result of the verification, either true or false. In case of false, all errors are provided, with an explanation. # Presentation Definitions Presentation Definitions define which credential(s) a Verifier requests and for what purpose. Which credentials is defined by the credential schema and the issuer. The resulting object is conformant with [W3C Presentation Exchange 1.0](https://identity.foundation/presentation-exchange/spec/v1.0.0/) specification and serves as input to a [Verification Request](https://github.com/Meeco/docs/blob/archive/2022-01/guides/oidc4vp.md). ## Prerequisites * [Verifiable Credential JSON Schema](/latest/guides/credential-schemas) * [Issuer DID](/latest/guides/dids/did-methods) (optional) ## Who can use this? Presentation definiton is created by an organisation. ## Create Presentation Definition Creation of a presentation definitions for an organisation. **Endpoint** ```bash POST /presentation_definitions ``` **Request** * Organisation (header) * Name * Purpose * List of required credentials. For each, the following is defined * Name * Purpose * Verifiable Credential JSON Schema URL * Issuer DID **Response** The presentation definition object that is created. Created Presentation Definition which associated with the Credential Schema and relates to the organisation which initiate creation of presentation definition ## Read Presentation Definitions ### List Retrieve a list of presentation definitions owned by an organisation. **Endpoint** ```bash GET /presentation_definitions ``` **Request** * Organisation (header) * Filters (optional): * Status **Response** List of presentation definitons in this organisation. ### One Object Retrieve a presentation definition by ID. The resulting object needs to be owned by the organisation that is making the request. **Endpoint** ```bash POST /presentation_definitions/{id} ``` **Request** * Presentation Definition ID * Organisation (header) **Response** A presentation definition object. ## Archive Presentation Definition Presentation definition can be archived and restored, and status of it affects to the ability of using this presentation definition in the future flow, such as beeing added to verification request. **Endpoint** ```bash PUT /presentation_definitions/{id} ``` **Request** * Presentation Definition ID * Organisation (header) **Response** Updated Presentation Definition Archive status for organisation, `is_archived: true` for archieved definitions, and `is_archived: false` for active or restored. ## Read Presentation Definition JSON Public endpoint that returns the JSON representation of presentation definition, following the [W3C Presentation Exchange 1.0](https://identity.foundation/presentation-exchange/spec/v1.0.0/) specification. **Endpoint** ```bash GET /presentation_definitions/{id}/definition.json ``` **Request** * Presentation Definition ID * Organisation (header) **Response** Returns JSON schema for a presentation definition # Vault # Setting up Access This guide contains step by step instructions on how to create user accounts for the ***Vault*** and the ***Keystore***. ![Create User with SRP](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/srp_create_user.svg) * The ***Keystore*** is where a users stores their secrets and encryption keys. * The ***Vault*** is where users store their encrypted user data. User data cannot be decrypted and read by anyone but the user. Once the user has been authenticated a mobile/web application interacts with the ***Vault*** and ***Keystore*** to securely store user's data and encryption keys. The mobile application and/or its backend will perform calls to the ***Vault*** and ***Keystore***. Generation of various keys, data encryption, and decryption will also happen on the client side. In order to simplify the client side cryptography Meeco has developed an open-source library which implements the required cryptographic routines. We've called it "Cryppo", and you can read about it and the languages it's available in on the [Cryppo page on this documentation site](https://github.com/Meeco/docs/blob/archive/2022-01/guides/tools/cryppo.md) Encryption of data and keys on the client side before it is sent up to the ***Keystore*** or ***Vault*** is an important part of the flow and infrastructure. By never sending unencrypted data to the services the layer of trust needed in a given service is greatly diminished and the likelihood of the data being decrypted by a nefarious entity should a data breach occur is extremely low. For this guide, in order to emulate client behavior we will use the [Meeco-CLI](https://github.com/Meeco/docs/blob/archive/2022-01/guides/tools/meeco-cli.md) to setup access to the ***Vault*** and ***Keystore*** and the [Cryppo-CLI](https://github.com/Meeco/docs/blob/archive/2022-01/guides/tools/cryppo.md#cryppo-cli) to generate keys and encrypt/decrypt some data. By the end of this guide, after reading and executing the scripts you will learn about which cryptographic keys exist for a user, and how they are encrypted and stored safely in the ***Keystore***. The guide also demonstrate how keys are encrypted and decrypted. ### Setting up Download the [Meeco-CLI](https://github.com/Meeco/cli) and the [Cryppo-CLI](https://github.com/Meeco/docs/blob/archive/2022-01/guides/tools/cryppo.md#cryppo-cli) and follow the installation instructions for each tool. If you'd like to read more about the tools, you can find each description page in the [Tools](https://docs.meeco.me/tools) section on this site. To explain what is required to access the Meeco ***Vault***, we're going to look in detail at what the Meeco CLI does when you create a new user. The CLI uses a Secret Key in combination with your user entered passphrase to generate both an encryption key and a password. The password is then used to authenticate using [Secure Remote Password protocol](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol) - otherwise known as SRP. Below is a diagram that explains the flow. ![](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/hwo_the_secret_key_is_built.png) ### Creating a User with the Secret Key Flow ```bash meeco users:create -p supersecretpassword > .user.yaml ``` The above command fires off a series of calls to the various Meeco APIs *'Generating username'* Firstly, we request a random username. It is a string that looks like `M9znjHbD5Xi`. We also need to generate a random "Secret" that looks like the following: `xQCSCK-8A1d6d-emUjx8-YVGDcT-UhctWy-2rfHyv-7JNAgh-9` . We combine the username and the secret, and prepend a version number to it. The resulting string is known as the "Secret Key" and takes the following form: `1.M9znjHbD5Xi.xQCSCK-8A1d6d-emUjx8-YVGDcT-UhctWy-2rfHyv-7JNAgh-9` Now that we have our secret key, it's time to derive the credentials that we need in order to create our user. We use the user's passphrase - `supersecretpassword` from the CLI command - and use the "Secret" as a salt to generate the "Passphrase Derived Key" (PDK). The PDK is later used to encrypt the "Key Encryption Key" (KEK). The passphrase derived key ends up looking like the following string: `24rdL_ugryujjDLcvwt00ARWWMCF4kk4gJETJy6yRjs=` We also generate an "SRP Password" which uses the *reverse* of the Secret Key as a salt. We're now ready to create a ***Keystore*** account. ## Creating A Keystore User Account *'*'*Create SRP keystore user'* The CLI uses the SRP Password and the SRP username in order to create a salt and a verifier, and sends this *plus* the SRP username to the ***Keystore*** API. Now, the CLI is going to log into the ***Keystore*** via SRP. *'Requesting SRP challenge from server'* From here, the server generates a challenge from that salt, and sends it back to the client (in this case, the CLI) to solve. Once the proof has been computed from the challenge, *'Creating SRP session with proof'* The server receives the solution and verifies it, which sends back a ***Keystore*** authentication token. Login to the ***Keystore*** is complete! Now we can access the ***Keystore***, generate keys to store in there, and request external admission tokens from it so that we can eventually access the Vault. ## Requesting Access To The Vault *'Request External Admission Tokens from the Keystore'* It is time for the CLI to get the required token so that it can get access to the ***Vault***. In order to restrict users from creating more than one user account in the ***Vault***, the vault account is created using an admission token we request from the ***Keystore***. The ***Keystore*** will request an admission token from the ***Vault*** on behalf of the user: This is how the CLI does this behind the scenes: ```bash curl -v -X GET "https://sandbox.meeco.me/keystore/external_admission_tokens" -H "Cache-Control: no-cache" -H "Meeco-Subscription-Key: DEV_PORTAL_SUBSCRIPTION_KEY" -H "Authorization: KEYSTORE_ACCESS_TOKEN" ``` The response contains the ***Vault*** API admission token, which the CLI will use later to get access to the ***Vault*** ```javascript "external_admission_token": { "vault_api_admission_token": VAULT_API_ADMISSION_TOKEN, "passphrase_store_admission_token": null } } ``` ## Generating the *Key Encryption Key* And Encrypting It *'Generate and store key encryption key'* The key encryption key (*KEK*) is a special encryption key which is used to encrypt all of the user’s other keys (data encryption keys and keypairs). There is only one *KEK* per user. The CLI uses the `cryppo` library to generate a new random key, and then encrypt and serializes it with the *PDK* from the earlier secert key steps. To do this manually, you can use the `cryppo-cli` library by using the following command with the unencrypted KEK you can find in the user's YAML file that the CLI creates in the root of the CLI directory: ```bash ➜ cryppo genkey URL-Safe Base64 encoded key: INUyR39qQcu43rqLeJtoTSMbzrB6NjlkSEujnM99ow4= ➜ cryppo encrypt -v INUyR39qQcu43rqLeJtoTSMbzrB6NjlkSEujnM99ow4= -k {PASSPHRASE DERIVED KEY} Aes256Gcm.XKa_28KCjz_qUICv3XDi3x2SFSWCgVj3kkxvBg1QcfnG0Zkn7ooonHrnV48=.LS0tCml2OiAhYmluYXJ5IHwtCiAgek5Sa004M2lwRFYvd1hhegphdDogIWJpbmFyeSB8LQogIGpzb0pWbjBNNytLWWpoU3p0c2lpb1E9PQphZDogbm9uZQo= ``` The resulting encrypted *KEK* looks like this: `Aes256Gcm.3EvCOUWD-zsHfe5hvrsMcppHx14SOMHXrEZC4Eyfw3s2JpvrIQRAH5Ydqcc=.LS0tCml2OiAhYmluYXJ5IHwtCiAgSVdjQ0M1ZC9FeHdRSVVFMAphdDogIWJpbmFyeSB8LQogIFN0L1o5QTZOMCswczBWQXgxcjQ0Rmc9PQphZDogbm9uZQo=` If you look at the serialized encrypted *KEK* you might notice it contains 3 parts concatenated with dots. This is the serialization format of `cryppo`. If no derived key is used, each such string contains 3 parts concatenated with a dot: * Encryption strategy name * Encrypted data encoded with Base64 * Encryption artefacts serialized into a hash converted to YAML, then encoded with Base64 #### Storing The Serialized Encrypted Key Encryption Key The CLI now stores the serialized and encrypted *KEK* in the keystore. ```bash curl -v -X POST "https://sandbox.meeco.me/keystore/key_encryption_key" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Meeco-Subscription-Key: DEV_PORTAL_SUBSCRIPTION_KEY" -H "Authorization: KEYSTORE_ACCESS_TOKEN" --data-ascii "{ ^"serialized_key_encryption_key^": ^"SERIALIZED_KEK_FROM_CRYPPO-CLI_OUTPUT" }" ``` Response from the server: ```javascript { "key_encryption_key": { "id": "4c43045d-7ff6-43b1-9700-53bf280f065a", "serialized_key_encryption_key": "SERIALIZED_KEK_FROM_CRYPPO-CLI_OUTPUT" } } ``` ## Generating the Data Encryption Key And Encrypting It *'Generate and store data encryption key'* *Data Encryption Keys* (DEKs) are used to encrypt data. A user can have different data encryption keys used for different purposes. For instance, you will have one for encrypting ***Vault*** data, and one per ***Connection*** that you create with a user. To store a *DEK* we need to encrypt it with the *Key Encryption Key*. This follows the same general form as generating and encrypting the *KEK*, but this time, we encrypt the *DEK* with the *KEK* instead of the *PDK*. ```bash ➜ cryppo genkey URL-Safe Base64 encoded key: FOQSBUavGP23Fnrgo3mgIfYjk7bLMLpkWLVXEVwg9AU= ➜ cryppo encrypt -v FOQSBUavGP23Fnrgo3mgIfYjk7bLMLpkWLVXEVwg9AU= -k {KEY_ENCRYPTION KEY} ``` #### Storing The Encrypted Data Encryption Key As with the *KEK*, we store the *DEK* in the ***Keystore***. The CLI uses the following API call: ```bash curl -v -X POST "https://sandbox.meeco.me/keystore/data_encryption_keys" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Meeco-Subscription-Key: DEV_PORTAL_SUBSCRIPTION_KEY" -H "Authorization: KEYSTORE_ACCESS_TOKEN" --data-ascii "{ ^"serialized_data_encryption_key^": ^"SERIALIZED_DATA_ENCRYPTION_KEY^" }" ``` Response: ```javascript { "data_encryption_key": { "id": "2a78322d-fe8a-4b69-af3d-bba3c66d0cd6", "serialized_data_encryption_key": "SERIALIZED_DATA_ENCRYPTION_KEY" } } ``` ## Generating a Keypair *'Generate and store vault key pair'* A user can have many keypairs for different purposes. A keypair can be tagged by the client to specify what the keypair is used for. We will generate a keypair which we'll use for authentication into the ***Vault***. Keypairs are stored in the following fashion: * Public keys are stored unencrypted * Private keys are encrypted with the Key Encryption Key The CLI will do the following: 1. Decrypt the encrypted KEK with the Passphrase Derived Key 2. Generate a RSA keypair with `cryppo` 3. Extract the public key 4. Encrypt the private key with the KEK The `cryppo-cli` code that does the above looks like this: ```bash ➜ cryppo genkeypair -P pubKey -p privKey Wrote new key pair ➜ cryppo encrypt -v "-----BEGIN RSA PRIVATE KEY----- { ... } -----END RSA PRIVATE KEY-----" -k {KEY ENCRYPTION KEY} ``` The CLI now has the encrypted Private Key ready to be uploaded to the ***Keystore*** #### Storing The Keypair Let's store the keypair. We will later use it for accessing the ***Vault***, therefore we'll tag it with `vault`: ```bash curl -v -X POST "https://sandbox.meeco.me/keystore/keypairs" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Meeco-Subscription-Key: acecb1c549ac4edb9deb4ea9c9ca8d01" -H "Authorization: lVrriqUgXfX8yr7JT7p1kcZIi6O2UMVsQsnK-NYUc0I=.EFBPrsntOlltcA2g79bbtkhmYAWB9p9VQRfEm6GUZa4=" --data-ascii "{ ^"encrypted_serialized_key^": ^"ENCRYPTED_SERIALIZED_PRIVATE_KEY^", ^"public_key^": ^"-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA8ZEqPqHpVgWvK+NT0SR2\noVom2dv6QStVeYqgFnKm6TvZy66Gl8gQs6KjbgHc9dEfceN6yrE3WfvOwItgJSsY\nmsZVjuSyyXYtW3rVPhIEtsw/HaBcoC1HP3tuk7+YLq1UVjeOBtAt9yrhcGpkU2f4\nMi4Z7q1MVxErX2cdAbe+LLSx6Gx0n3hqPrmpMG6ZRoZ3dc4xNifs7K1RIt6hVSfy\nhIjgDr3Ret98CG+Vm5mJ3Vd5/BG0UE/j0NyKoGlqJg3VrJEVXcQoQ4DsUGj2GMu1\nj3DjyIn64ba4F2qpK4bJ6QcKGZsgr5K17KDguGBJ9B6HJ3PPd4oSSDHq7wfpu+bT\nNzN4NJ+eyIQJqYbwj1e18ETwHcogc2jpzGUHSEs1rTiUEibRFRUkqtlk4bXar/tz\n0II7bV9hIlhOaf9urqDwCtkN34p/h36eDqDxCaDeg4QtjBuZu9IgizrxHQZD5j8H\ntAhkULG6NqrAAynRxBDM+0kmZr+uzEL155YPnezIAoeCj8NlwkcUCm2ZCcQkA3AK\nvrkqGEOAm9QYqpyjpujjDDVgQNZXiQnWg94DG6CnRFqyFRPOfVKyhmcziqL1ejfV\ngPyrIHiU/5dmFu5LbmDjaUIX6j3DvYbXy87dPxsOESmeQWFQGY3REN+ZSwS+3FAP\n1aTS4Bwim9RiPycM3MY2vTUCAwEAAQ==\n-----END PUBLIC KEY-----\n",^", ^"metadata^": {}, ^"external_identifiers^": [ ^"vault^" ] }" ``` Response: ```javascript { "keypair": { "id": "8b261bdc-2526-4a7f-b403-61f357a847c2", "public_key": "-----BEGIN PUBLIC KEY-----\nPUB_KEY_CHARACTERS\n-----END PUBLIC KEY-----\n", "encrypted_serialized_key": "Aes256Gcm.REST_OF_CHARACTERS", "metadata": {}, "external_identifiers": [ { "id": "83357673-92fd-4928-bef3-741352af6f62", "identifier": "vault", "keypair_id": "1320c3fb-8a58-411c-9c76-ba13b3e4def7" } ] } } ``` ## Creating a Vault User Account *'Create Vault API User'* Here, the CLI is using the admission token that it got from the 'Request External Admission Tokens from Keystore' step earlier on. Importantly, this call is made to the ***Vault*** API instead of the ***Keystore*** API An *admission token* can only be used once. You can think of it like a ticket for a plane ride - once you're in, you can't use it again! To create a vault user account we'll submit: * The *admission token* * The *public key* from the keypair we generated. ```bash curl -v -X POST "https://sandbox.meeco.me/vault/me" -H "Content-Type: application/json" -H "Cache-Control: no-cache" -H "Meeco-Subscription-Key: DEV_PORTAL_SUBSCRIPTION_KEY" --data-ascii "{ ^"public_key^": ^"-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA8ZEqPqHpVgWvK+NT0SR2\noVom2dv6QStVeYqgFnKm6TvZy66Gl8gQs6KjbgHc9dEfceN6yrE3WfvOwItgJSsY\nmsZVjuSyyXYtW3rVPhIEtsw/HaBcoC1HP3tuk7+YLq1UVjeOBtAt9yrhcGpkU2f4\nMi4Z7q1MVxErX2cdAbe+LLSx6Gx0n3hqPrmpMG6ZRoZ3dc4xNifs7K1RIt6hVSfy\nhIjgDr3Ret98CG+Vm5mJ3Vd5/BG0UE/j0NyKoGlqJg3VrJEVXcQoQ4DsUGj2GMu1\nj3DjyIn64ba4F2qpK4bJ6QcKGZsgr5K17KDguGBJ9B6HJ3PPd4oSSDHq7wfpu+bT\nNzN4NJ+eyIQJqYbwj1e18ETwHcogc2jpzGUHSEs1rTiUEibRFRUkqtlk4bXar/tz\n0II7bV9hIlhOaf9urqDwCtkN34p/h36eDqDxCaDeg4QtjBuZu9IgizrxHQZD5j8H\ntAhkULG6NqrAAynRxBDM+0kmZr+uzEL155YPnezIAoeCj8NlwkcUCm2ZCcQkA3AK\nvrkqGEOAm9QYqpyjpujjDDVgQNZXiQnWg94DG6CnRFqyFRPOfVKyhmcziqL1ejfV\ngPyrIHiU/5dmFu5LbmDjaUIX6j3DvYbXy87dPxsOESmeQWFQGY3REN+ZSwS+3FAP\n1aTS4Bwim9RiPycM3MY2vTUCAwEAAQ==\n-----END PUBLIC KEY-----\n^", ^"admission_token^": ^"2571b0b6c580a7785c8b^" }" ``` The response is as follows: ``` { "encrypted_session_authentication_string": "string", "user": { "id": "string", "private_encryption_space_id": "string", } ``` The response contains * ID of the user in the ***Vault*** * an encrypted session token To decrypt the encrypted session authentication token, the CLI feeds the private key and the encrypted session authentication token into `cryppo`. The Cryppo-CLI can do this for you with the following command. ```bash ➜ cryppo decrypt -s {encrypted_session_authentication_string} --privateKeyFile {PRIVATE KEY FILE FROM EARLIER KEYPAR GENERATION TO FILE} ``` The output is then used in the next step for creation the encryption space for the new User. *'Update Vault Encryption Space'* The final job for the CLI is to create a new encryption space for the user. This is a DEK identifier. ## Logging In Into The Vault Once decrypted, encrypted session token can now be used with the `Authorization` header to work with the ***Vault***. ## Next Steps The Login flow has been completed, and now you can use the token to try out the API calls in the ***Vault*** at the [Meeco Developer Portal playground for the Vault](https://dev.meeco.me/api-details#api=meeco-vault-api) If you created a user in the CLI, you can use the tokens and keys in the metadata section of your `.user.yaml` files to try out more API requests. # Items and Slots This guide describes creating Items and Item Templates using the Meeco API. ## Basic Terms * **Name** — A *machine-readable* non-empty string, for example `phone_number` or `postal_address`. * **Label** — A *human-readable* non-empty string, for example "Phone Number", or "Postal Address". Objects often have both a name and a label with a direct relationship between the two, as suggested by the example. * **Slot** — The smallest data entity in the vault. Each slot has a name, a label, and a value. Values can be strings, dates, or numbers, but also binaries like images or documents. Values are always encrypted. [Read more](https://github.com/Meeco/docs/blob/archive/2022-01/guides/vault/terminology.md#slot) * **Item Template** — A list of empty slots with a label and a name. Each Item is created by cloning such a template and filling in the slots. More detail about [Item Templates in the Terminology section](https://github.com/Meeco/docs/blob/archive/2022-01/guides/vault/terminology.md#an-item-template) * **Item** — Contains one or more slots with filled in values. Read more about [Items in the Terminology section](https://github.com/Meeco/docs/blob/archive/2022-01/guides/vault/terminology.md#item) ## Browsing Item Templates Items are created from templates, so we begin by listing all available Item templates: ```bash curl --request GET 'https://sandbox.meeco.me/vault/item_templates' \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" ``` [API docs](https://dev.meeco.me/api-details#api=meeco-vault-api\&operation=get-item_templates-id) (Get `API_SUBSCRIPTION_KEY` by [signing up](https://dev.meeco.me/signup) for the API, then use the CLI tool to [generate a User and access token](https://github.com/Meeco/js-sdk/tree/master/packages/cli).) The response JSON object lists Templates under the `item_templates` key. Each Template object has a `slot_ids` list, which references Slots in the top-level `slots` list. Here is a truncated sample response: ```json { "item_templates": [ { "id": "ccfaadf6-e040-433f-ad34-904e988a2187", "name": "travel", "description": null, "ordinal": 10, "visible": true, "user_id": null, "updated_at": "2020-01-02T20:32:49.991Z", "template_type": "ItemTemplate", "classification_node_ids": [], "label": "Travel", "background_color": null, "image": "https://api-sandbox.meeco.me/images/7308dc39-d2b1-4039-9960-34f69dd06cd7", "association_ids": [], "associations_to_ids": [], "slot_ids": [ "0cf77509-6eaf-49ff-a036-c3c7e2fee106", "f1668277-0db5-4cff-9210-08a2f245c4aa", "23eea243-1d09-4000-9215-7c1bc534c141", "b57a5d9a-f124-4ddd-954f-18681b2360f1", "929ea8b9-9815-4389-99a9-163f9e0c8b15" ] }, ... ], "slots": [ { "id": "f1668277-0db5-4cff-9210-08a2f245c4aa", "name": "return_date", "description": null, "encrypted": false, "ordinal": 2, "visible": true, "classification_node_ids": [], "slotable_id": "ccfaadf6-e040-433f-ad34-904e988a2187", "slotable_type": "ItemTemplate", "required": false, "updated_at": "2020-01-02T20:32:49.761Z", "created_at": "2020-01-02T20:32:49.761Z", "config": null, "slot_type_name": "date", "creator": "system", "binary_ids": [], "label": "Return date", "image": null, "encrypted_value": null }, ... ], "shares": [], "classification_nodes": [ ... ], "associations": [], "associations_to": [], "attachments": [], "thumbnails": [], "meta": { "pages": null, "total_count": null } } ``` Here's a sample of Item Templates you might get: * `passport_details` * `password` * `important_document` * `vehicle` * `travel` * `bank_item` * `membership_subscription` * `pet` * `device` * `important_document` * `custom` * `services` ### Finding a Specific Template You can get a specific Template using its `id` (replace `ITEM-TEMPLATE-ID`): ```bash curl --request GET 'https://sandbox.meeco.me/vault/item_templates/ITEM-TEMPLATE-ID' \ -H 'Authorization: Bearer $VAULT_ACCESS_TOKEN' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' ``` [API docs](https://dev.meeco.me/api-details#api=meeco-vault-api\&operation=get-item_templates-id) Or, to search Item Templates by matching `label` text (replace `SEARCH_TEXT`): ```bash curl --request GET 'https://sandbox.meeco.me/vault/item_templates?like=SEARCH_TEXT' \ -H 'Authorization: Bearer $VAULT_ACCESS_TOKEN' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' ``` [API docs](https://dev.meeco.me/api-details#api=meeco-vault-api\&operation=get-item_templates-id) ## Creating an Item The example below creates an Item from the `vehicle` Template. Using the CLI, we can see that the `vehicle` Template has the following Slots: * `model_make` * `licence_plate` * `vin` * `type` * `purchase_date` For now the new Item's Slots are left empty. A [later section](#encryption-of-user-data) will cover encrypting data and adding it to a created Item. To create an Item you must give the name of an existing Item Template, and a label: ```bash curl --request POST 'https://sandbox.meeco.me/vault/items' \ -H 'Authorization: Bearer $VAULT_ACCESS_TOKEN' \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ --data \ '{ "template_name": "vehicle", "item": { "label": "My Car" } }' ``` [API docs](https://dev.meeco.me/api-details#api=meeco-vault-api\&operation=post-items) The API response is the newly created Item: ```json { "item": { "id": "e053853d-6a7e-476b-8e3b-d78b4e6d2802", "name": "vehicle", "label": "Vehicle", "description": null, "created_at": "2020-03-12T04:38:24.110Z", "item_template_id": "61516c6f-81df-4c86-96df-8af915f0aec0", "ordinal": 1, "visible": true, "updated_at": "2020-03-12T04:38:24.556Z", "item_template_label": "Vehicle", "shareable": false, ... "association_ids": [], "associations_to_ids": [], "slot_ids": [ "f84d82be-7d82-4ccb-b7ae-e30be5b036c9", "6e1e4ecc-0b8b-45c1-919f-01e69f05bbf8", "f09975cc-ec8e-4744-b883-73c115d32434", "32d1f51b-d26e-4c85-8589-133a4f8e4579", "5addd943-948d-4f80-b1e8-771ff5fee2c1", "1fdd1473-a178-43dc-8862-c1aa242cf861", "e4d7f7ed-de2c-4819-9369-478f2357b6aa", "4cd09df4-9b69-4579-9e76-9a6d7c314b02" ] }, "classification_nodes": [], "shares": [], "connections": [], "attachments": [], "thumbnails": [], "slots": [ { "id": "f84d82be-7d82-4ccb-b7ae-e30be5b036c9", "name": "image", "description": null, "encrypted": false, "ordinal": 6, "visible": true, "classification_node_ids": [], "slotable_id": "e053853d-6a7e-476b-8e3b-d78b4e6d2802", "slotable_type": "Item", "required": false, "updated_at": "2020-03-12T04:38:24.531Z", "created_at": "2020-03-12T04:38:24.531Z", "config": null, "slot_type_name": "image", "creator": "system", "binary_ids": [], "label": "Image", "image": null, "encrypted_value": null }, ... ], "associations": [], "associations_to": [] } ``` Notice that Slots are created according to the Item Template, but are left empty for now. Items can also be classified, that is described in [another page](/latest/guides/vault/classification-hierarchies). ### Item Names An Item's `name` is auto-generated from its label. Names are all lower-case, have no non-alphanumeric characters, and have whitespace replaced with underscores. For example, label `A strange &8Label` would become `a_strange_8label`. Any user specified names (for Slots and Items) are sanitized to this format. Item names and labels do not have to be unique, unlike Item Template names. ### Extra Slots The Slots in the Item Template are present in every Item created from that Template, but Items can have additional Slots too. Any extra Slots described in `slots_attributes` are created for the new Item. For example, if `my_template` had Slots `foo` and `bar`, and we create an Item with ```json { "template_name": "my_template", "item": { "label": "A Test Item", "slots_attributes": [ { "label": "baz", "slot_type_name": "key_value" } ] } } ``` Then the new Item will have Slots `foo`, `bar` and `baz`. The next section has more information about creating Slots. ## Creating a Custom Template It is possible to create a Custom Template which we can use to create our own Items. Only the `label` property is required, it will auto-generate a `name` (as described above). Since Item Templates are referenced by their name, the generated name must be unique. You can specify it separately if the label does not generate a unique name. ```bash curl --request POST "https://sandbox.meeco.me/vault/item_templates" \ -H "Content-Type: application/json" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ -H "authorization: Bearer $VAULT_ACCESS_TOKEN" \ --data \ '{ "name": "example_custom_template", "label": "Example Custom Template", "description": "An example template", "slots_attributes": [ { "label": "An Example Slot", "slot_type_name": "key_value" } ] }' ``` The new Template will look like this: ```json { "item_template": { "id": "66c6b284-434e-4411-9435-7bd70a74c6d2", "name": "example_custom_template", "description": "An example template", "ordinal": 0, "visible": true, "user_id": "68a2cdb3-4a9d-42ac-83e7-d7e4967143a0", "updated_at": "2020-09-28T02:03:11.348Z", "label": "Example Custom Template", "slot_ids": [ "e019d2a6-36ed-4768-9aec-273879273d23" ], "classification_node_ids": [], "background_color": null, "image": null }, "slots": [ { "id": "e019d2a6-36ed-4768-9aec-273879273d23", "name": "an_example_slot", "description": null, "encrypted": false, "ordinal": 0, "visible": true, "classification_node_ids": [], "item_id": null, "required": false, "updated_at": "2020-09-28T02:03:11.424Z", "created_at": "2020-09-28T02:03:11.376Z", "config": null, "slot_type_name": "key_value", "creator": null, "label": "An Example Slot", "image": null, "attachment_id": null, "own": false, "share_id": null, "original_id": null, "owner_id": null, "encrypted_value": null, "encrypted_value_verification_key": null, "value_verification_hash": null } ], "classification_nodes": [], "attachments": [], "thumbnails": [] } ``` Then, you can create an item from your new template: ```bash curl --request POST "https://sandbox.meeco.me/vault/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "An example item with custom template", "slots_attributes": [] }, "template_name": "example_custom_template" }' ``` The created item comes back looking like the following, with a custom slot that was part of the template creation call. ```json { "item": { "id": "98db3af3-c430-45ce-a5eb-cce89b19f736", "name": "an_example_item_with_custom_template", "label": "An example item with custom template", "description": "An example template", "created_at": "2020-09-28T02:12:56.194Z", "item_template_id": "66c6b284-434e-4411-9435-7bd70a74c6d2", "ordinal": 1, "visible": true, "updated_at": "2020-09-28T02:12:56.271Z", "item_template_label": "Example Custom Template", "item_image": null, "item_image_background_colour": null, "slot_image": null, "slot_image_background_colour": null, "category_image": null, "category_image_background_colour": null, "category_label": null, "original_id": null, "owner_id": "68a2cdb3-4a9d-42ac-83e7-d7e4967143a0", "share_id": null, "image": null, "image_background_colour": null, "me": false, "background_color": null, "classification_node_ids": [], "association_ids": [], "associations_to_ids": [], "slot_ids": [ "445ee1d0-0100-458d-9f7a-4698b6aaf1f0" ], "own": true }, "associations": [], "associations_to": [], "classification_nodes": [], "slots": [ { "id": "445ee1d0-0100-458d-9f7a-4698b6aaf1f0", "name": "an_example_slot", "description": null, "encrypted": false, "ordinal": 0, "visible": true, "classification_node_ids": [], "item_id": "98db3af3-c430-45ce-a5eb-cce89b19f736", "required": false, "updated_at": "2020-09-28T02:12:56.247Z", "created_at": "2020-09-28T02:12:56.247Z", "config": null, "slot_type_name": "key_value", "creator": "user", "label": "An Example Slot", "image": null, "attachment_id": null, "own": true, "share_id": null, "original_id": null, "owner_id": "68a2cdb3-4a9d-42ac-83e7-d7e4967143a0", "encrypted_value": null, "encrypted_value_verification_key": null, "value_verification_hash": null } ], "attachments": [], "thumbnails": [] } ``` Notice that the Item's `description` property inherits the `description` of the Item Template. There are a few limitations on the use of Item Templates: * There currently isn't a way to share custom templates with other users. * Templates cannot be changed or deleted ### Slots Slots represent a key-value pair, where the value is always encrypted. The Meeco Vault will check and reject any `encrypted_value` data that doesn't match the cryppo serialization format. Slots are always owned by an Item (or an Item Template, but these Slots are never read), and news Slots are created for each new Item. Their most important properties are: | Property | Description | | ----------------- | --------------------------- | | `name` | Machine-readable string | | `label` | Display name | | `description` | Longer name | | `encrypted_value` | Output of Cryppo encryption | | `slot_type_name` | string | The `slot_type_name` property must be one of * `key_value` * `bool` * `classification_node` * `color` * `date` * `datetime` * `image` * `note_text` * `select` * `attachment` * `url` * `phone_number` * `select_multiple` * `email` * `password` As the Vault cannot inspect the data, it is just a suggestion to the user. Type `key_value` is the default. Slots are created either by cloning an Item Template, or via the `slots_attributes` property when creating an Item. Since they are keyed by `name`, either `label` or `name` must be non-empty on creation. Slots are updated by calling `PUT /vault/items` with the new data in `slots_attributes`: ```bash curl --request PUT "https://sandbox.meeco.me/vault/items/bef961af-aa1f-4f1c-ac95-cdb41b3682db" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "slots_attributes": [ { "name": "bar", "label": "A new label" } ] } }' ``` As Slots are keyed by their names, names should be unique per Item. Slots can also be deleted by calling `DELETE /slot/id`. This deletes the Slot (and it's data) from the parent Item. Slots in Item Templates cannot be deleted. ## Encryption of User Data One of the core features of the Meeco platform is data encryption. User data stored in the Meeco Vault is encrypted in such a way that no one - including Meeco - can decrypt and read it other than the user. If we want to store data in an Item we must encrypt it, otherwise the Vault will return an error. To get familiar with the kinds of cryptographic key the Meeco platform uses please follow either the [Quickstart](https://github.com/Meeco/docs/blob/archive/2022-01/guides/getting-started/quickstart.md) guide, or "[Setting Up Access to the Vault and Keystore](/latest/guides/vault/setting-up-access)". That will introduce you to the Cryppo library that we use to make encryption, decryption and serialization simpler in the context of the Meeco Service. In the following example, we will use the Data Encryption Key (DEK) that the CLI generated for us from the Quickstart guide (and saved into the \`.user.yaml\` file) to encrypt a Slot value. In the real world this process would involve a few more steps: * Reading the encrypted Key Encryption Key (KEK) from the Key Store * Decrypting it with the Password Derived Key (PDK) * Reading a DEK from the Key Store * Decrypting it with the KEK If you do not have a DEK already, you can also generate one using the \`cryppo-cli\` and the following command: ```bash cryppo genkey ``` Result: ```bash URL-Safe Base64 encoded key: 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg= ``` To encrypt slot value \`BMW\` run the following command: ```bash cryppo encrypt -v BMW -k 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg= ``` Result: ```bash Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo= ``` The output above is the encrypted slot value ready to be stored in the Vault. We can decrypt by running the following command: ```bash cryppo decrypt -s Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo= -k 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg= BMW ``` The Meeco platform uses the serialization format of Cryppo. If no derived key is used, each such string contains three parts concatenated with a dot: * Encryption strategy name * Encoded encrypted data encoded with Base64 * Encoded encryption artefacts serialized into a hash converted to YAML, then encoded with Base64 If you are feeling adventurous you are welcome to dig into the [Cryppo-CLI](https://github.com/Meeco/cryppo-cli) The example below creates an Item config file. We need to provide a template name to create an item config file. ```bash meeco items:create-config TEMPLATENAME > .item_config.yaml ``` This command will create the config file for the item to be created in the next step. The TEMPLATENAME can be any template from the list above. The Meeco CLI can then create the item by the following command: ```bash meeco items:create .item_config.yaml ``` will create the Item encrypting the Slots described in `.item_config.yaml` using the current user's keys. You can also integrate this flow into your app using the Meeco SDK's `UserService`. ### Filling Slot Values Thanks to the Item Template our new Item already has a list of empty Slots, and a list of classification tags. Let's fill in a value of the \`encryptedvalue\` slot using the encrypted value from the previous step: ```bash curl --request PUT \ 'https://sandbox.meeco.me/vault/items/049740cb-ad1f-43d9-9254-ae25eba30f47' \ -H 'Authorization: $VAULT_ACCESS_TOKEN' \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ -d ' { "item": { "label": "vehicle", "slots_attributes": [ { "label": "Make or model", "encrypted_value": "Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo=", "slot_type_name": "key_value", "name": "model_make" } ] } } ' ``` Response: ```json { "item": { ... }, ... "slots" [ ... { "id": "ce9d89f8-a50a-486a-b007-d1cb006ee157", "name": "model_make", "description": null, "encrypted": true, "ordinal": 1, "visible": true, "classification_node_ids": [], "slotable_id": "049740cb-ad1f-43d9-9254-ae25eba30f47", "slotable_type": "Item", "required": false, "updated_at": "2020-03-18T06:49:31.160Z", "created_at": "2020-03-18T06:49:17.549Z", "config": null, "slot_type_name": "key_value", "creator": "system", "binary_ids": [], "label": "Make or model", "image": null, "encrypted_value": "Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo=" }, ], } ``` ## Shared Items The page on [Connections and Sharing](/latest/guides/vault/connections-and-sharing) covers sharing Items. This section will just describe some properties of shared Items. ### Receiving A Share You receive a shared item by calling `PUT https://sandbox.meeco.me/vault/incoming_shares/{share_id}/accept`. (This indicates you accept the share terms, if any). Next call `GET https://sandbox.meeco.me/vault/incoming_shares/{share_id}/item` and view the Item that has been created in your Vault. Note that `share.item_id` is the original Item's id, not the one in your Vault! ### Owners An Item's owner is its original creator. The following table summarizes the how properties of an Item change when you are the owner, vs the receiver of a shared copy. | Property | Owner Vaule | Receiver Value | | ------------- | ----------- | --------------- | | `own` | true | false | | `original_id` | null | `share.item_id` | | `share_id` | null | `share.id` | As a result, if `item.share_id` is non-null, then it is a share you received, and you can view the share via `GET https://sandbox.meeco.me/vault/incoming_shares/{item.share_id}`. Owners have the ability to push updates of shared data, and can share the Item with anyone. Receivers of a shared Item can only share that Item if `item.sharing_mode` is `anyone`. # Connections and Sharing How to create a connection between you and another user to share data ### A follow along guide using the Meeco CLI to build on the Quickstart Guide *Below the guide using the CLI we have a more in depth explanation of how sharing works* After successfully creating an item in your user's Vault from the [Quickstart section](https://github.com/Meeco/docs/blob/archive/2022-01/guides/getting-started/quickstart.md), it's now time to create another user called Bob. ```bash meeco users:create -p supersecretpassword > .bob.yaml ``` We used the same password as in the [Quickstart](https://github.com/Meeco/docs/blob/archive/2022-01/guides/getting-started/quickstart.md) example, in case you were wondering. Using the CLI again, we're going to make a connection configuration file between *Alice* and *Bob* ```bash meeco connections:create-config --from .alice.yaml --to .bob.yaml > .connection_config.yaml ``` This creates a file called `.connection_config.yaml` which we will open and edit the `fromName` and `toName` keys. Let's make it between Alice and Bob. Next, it's time to use the CLI again to create the connection between the two users. ```bash meeco connections:create -c .connection_config.yaml > .connection.yaml ``` This generates the keypairs for the connection, creates and accepts the invitation for the two users. Now, we're ready to select an item from Alice's vault and share it with Bob. First, we'll need to create the share template with the CLI. ```bash meeco shares:create-config --from .alice.yaml -c .connection.yaml -i .item.yaml > .share_config.yaml ``` After this configuration file is created, we can create the share between the two users: ```bash meeco shares:create -c .share_config.yaml > .share.yaml ``` The output is a new shares item: ```bash shares: - id: 0f894916-852a-4682-bd49-0783ab58e1c0 owner_id: ab9f9fce-db0b-4384-a221-617efa80dba7 sender_id: ab9f9fce-db0b-4384-a221-617efa80dba7 recipient_id: ce021e77-a66f-4fae-a150-d3a4a6e1a7f9 acceptance_required: acceptance_not_required item_id: bae62ab6-ea95-4037-8f6c-3708c81b2d77 slot_id: null public_key: "-----BEGIN PUBLIC KEY-----\r ... -----END PUBLIC KEY-----\r\n" ... sharing_mode: owner keypair_external_id: f0ab31a1-c95d-463d-b6b1-1a72e1f56444 encrypted_dek: Rsa4096.Jm9R1Ve2KcOLc4-HkZkjviB8HXBSlVQLfTlUJ-xcGRRklBp-Od-g2YjareSFwMorzVrtVDKWg8QWkB3iDAn_g9pG3c-kY1Le5Gb86VTO3hhx74jImf_iw29VUUcAsfRQH2u69X5byyYYlg827nMpT8CgN4P3USsMsMMsXrppu7ONGwk-xxItJtr8S3cONECp5L_4cbcR4IDbGBpVGZMdU5X6YU3ZZ7z-fi5wF5tRp6krR4V8rqbJOlyURY2xwj3ihoGtPc6Dbef_H6viFEgl00gyDegXKgJ8IisES_6_cyq7ooiGbux5oTgyg4tTIA40Lf65JLzVujosFC56EatRumR-YretG_Dkr61PQfuGN2zpTOGpZzypnc-HJc-GCHWGLU1wqwhcBY3NNoM1NvmdWGRQV2Vrtt3rhBCM2Nt-E7lCyQTX45qGXG-q-nL2b6l_DfCfp6O5s4hAYVoBQgDLCexl1YFb0reNm1Ol3rQ_hjpPn9LHAgE93Mdq7b04-sBmbNF54oLyrAneZu8NOle1-dioK13dLNooSm_O5MuRdnjyaJZH5zcsN-mEeSzsTHBymiMitet1-YOoZrenLDUaaFpWj6fCgwW6louU7u8PWq8U40TV15c8TndQAVFyRhfPav8HHLhOJmOCa1HaqdGZ8vuw1efJW3rtOU2ye31JQIw=.QQUAAAAA terms: null created_at: 2020-09-24T07:15:03.315Z expires_at: null ``` The CLI sets up a *private encryption space* between Alice and Bob and then shares the item. We never created an item for the Bob, so we know that the following command will show the item that has been shared with Bob. ```bash meeco shares:get-incoming -a .bob.yaml ``` The following is the share information, as well as the item that was shared: ```bash share: id: 0f894916-852a-4682-bd49-0783ab58e1c0 owner_id: ab9f9fce-db0b-4384-a221-617efa80dba7 sender_id: ab9f9fce-db0b-4384-a221-617efa80dba7 recipient_id: ce021e77-a66f-4fae-a150-d3a4a6e1a7f9 acceptance_required: acceptance_not_required item_id: bae62ab6-ea95-4037-8f6c-3708c81b2d77 slot_id: null ... sharing_mode: owner keypair_external_id: f0ab31a1-c95d-463d-b6b1-1a72e1f56444 encrypted_dek: Rsa4096.Jm9R1Ve2KcOLc4-HkZkjviB8HXBSlVQLfTlUJ-xcGRRklBp-Od-g2YjareSFwMorzVrtVDKWg8QWkB3iDAn_g9pG3c-kY1Le5Gb86VTO3hhx74jImf_iw29VUUcAsfRQH2u69X5byyYYlg827nMpT8CgN4P3USsMsMMsXrppu7ONGwk-xxItJtr8S3cONECp5L_4cbcR4IDbGBpVGZMdU5X6YU3ZZ7z-fi5wF5tRp6krR4V8rqbJOlyURY2xwj3ihoGtPc6Dbef_H6viFEgl00gyDegXKgJ8IisES_6_cyq7ooiGbux5oTgyg4tTIA40Lf65JLzVujosFC56EatRumR-YretG_Dkr61PQfuGN2zpTOGpZzypnc-HJc-GCHWGLU1wqwhcBY3NNoM1NvmdWGRQV2Vrtt3rhBCM2Nt-E7lCyQTX45qGXG-q-nL2b6l_DfCfp6O5s4hAYVoBQgDLCexl1YFb0reNm1Ol3rQ_hjpPn9LHAgE93Mdq7b04-sBmbNF54oLyrAneZu8NOle1-dioK13dLNooSm_O5MuRdnjyaJZH5zcsN-mEeSzsTHBymiMitet1-YOoZrenLDUaaFpWj6fCgwW6louU7u8PWq8U40TV15c8TndQAVFyRhfPav8HHLhOJmOCa1HaqdGZ8vuw1efJW3rtOU2ye31JQIw=.QQUAAAAA terms: null created_at: 2020-09-24T07:15:03.315Z expires_at: null associations_to: [] associations: [] attachments: [] classification_nodes: - id: 8670d4c6-8d68-49a4-bd21-0fc8cefa705d name: vehicle label: Vehicle description: null ordinal: 3 background_color: null image: https://sandbox.meeco.me/vault/images/ff1c25e9-530a-4103-b649-986631bcAAAAA scheme: meeco item: id: a3f632c8-f80f-47aa-9e26-aab15ad9ed63 own: false name: a_new_item label: A New Item description: null created_at: 2020-09-24T07:15:03.452Z item_template_id: 0c385f1d-8825-4932-a6ab-846178b816e4 ordinal: 0 visible: true updated_at: 2020-09-24T07:15:03.493Z ... ``` Running `meeco shares:list -a .bob.yaml` will show all the shares information that Bob has received, even from other users. `meeco shares:list -t outgoing -a .alice.yaml` will show all the shares that are outgoing from Alice to other users. If you're looking for a way to delete the share, you can do that as either user with `meeco shares:delete -a .alice.yaml ` or `meeco shares:delete -a .bob.yaml ` Well done - you've now created a connection between two users, and shared an item! ## Sharing Items Between Users - In Depth All user data stored in the Vault is encrypted and can only be decrypted and read by the user. However, the Meeco platform makes it possible for one user to share items with another user. We will cover this process and its steps in this guide. In summary, the sharer will generate a DEK (data encryption key) specifically for the purpose of this share and re-encrypt the shared item with this key. In order to share the DEK, Public Key cryptography is used: the sharer will encrypt the DEK with a Public Key of the share recipient, so only the share recipient can decrypt the DEK with their Private Key, and then use the DEK to decrypt the item. ![](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/section3.png) Let's dive into it. ### Invitation To Connect Before anything can be shared, 2 Users need to establish a ***connection***. In order to create a connection in this example, User 1 (Alice) will invite User 2 (Bob) The process can be described in the following sequence diagram: ![](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/send_invitation.png) At step (1) User 1 generates a Keypair which will be used for inviting another user, and later for the key exchange. Steps 2-4 are part of the standard procedure used for storing Keypairs in the Keystore. If there is a Keypair, it is encrypted by the Key Encryption Key (KEK) and stored in the Keystore. Please read guide [Setting Up Access to the Vault and Keystore](/latest/guides/vault/setting-up-access) if you haven't read it yet. In steps 5 and 6, stores the Public Key. In steps 5-7 User 1 creates an invitation using the following as input: * email of the user that User 1 wants to connect to (User 2) * the Public Key After step 7 the Vault sends an invitation email to User 2. ### Accepting Invitation In this section we'll describe the scenario when User 2 accepts the invitation from User 1. This process can be described in the following sequence diagram: ![](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/accept_invitation.png) Most of these steps are the the same steps of User 1 in the previous section: just like User 1, User 2 generates a Keypair for this connection (step 9), encrypts it and stores in the Keystore (steps 10-12), and publishes the Public Key in the Vault (steps 13-14). The most important step is a call to create a connection as step 13. The parameters of the call are the invitation ID and the invitation token. The most important results after these two sections are as follows: * The connection between User 1 and User 2 has now been established * User 1 has access to the Public Key of User 2 on the connection record * User 2 has access to the Public Key of User 1 on the connection record ### Creating A Share In this section, to create a share, User 1 will generate a DEK dedicated to this share, re-encrypt a item and store it as a share, and share the DEK with User2, encrypted by the Public Key of User 2. Creation of a share can be described in the following sequence diagram: ![](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/create_share.png) At step 19 User 1 generates a DEK. This DEK will be used to encrypt the shared item. We also need to have the key readable by User 2, so at step 20 we encrypt the same DEK with the Public Key of User 2. In steps 21-23 User 1 encrypts the item data with the shared DEK and creates a Share record. The main results of these steps are as follows: * A DEK has been created and encrypted with User 2's public key * A Share record has been created in the Vault with the encrypted DEK, and it is linked to the connection between User 1 and User 2 ### Reading The Share Reading of the share can be described in the following sequence diagram: ![](https://github.com/Meeco/docs/blob/archive/2022-01/guides/.gitbook/assets/read_share.png) First in step 24 User 2 retrieves a list of all items both his own and shared incoming. If there is a new share User 2 needs to decrypt and read, in step 26 User 2 requests the share details. User 2 also retrieves the DEK in steps 26-27, decrypts it with their Private Key in step 28 and decrypts the share in step 29. # Classification Hierarchies In the Meeco Vault, Items, Item Templates and Slots can be tagged with **Classification Nodes**. If an Item has been tagged with a Classification Node, you can find it again by searching for that Classification Node. Classification Nodes are a lot like tags, but are grouped into Schemes. Schemes might represent similar topics, or classifications from an existing app. A Classification Node is structured like | Property | Type | Description | | ----------- | ------ | ------------------------------------------- | | name | string | Machine-readable name | | label | string | Human-readable name | | description | string | Explains what the classification represents | | scheme | string | See [Schemes](#schemes) | ## Browsing Classification Nodes The `$VAULT_ACCESS_TOKEN` can be grabbed from the user file you created in the [Quickstart](https://github.com/Meeco/docs/blob/archive/2022-01/guides/getting-started/quickstart.md) guide. All classification nodes can be queried by `GET /vault/classification_nodes`: ```bash curl --request GET \ 'https://sandbox.meeco.me/vault/classification_nodes' \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" ``` [API Docs](https://dev.meeco.me/api-details#api=meeco-vault-api\&operation=get-classification_nodes) You can modify the request with the following query parameters: * `scheme_name`, see below * `by_name` - a "LIKE" search which will return results for partial matches - i.e. 'fin' will return 'financial' ## Schemes Classification Nodes are grouped by Schemes. Available Schemes are set by the Vault and cannot be changed. These are the existing schemes: * `tag` * `country` * `meeco_wallet` * `region` You must use `tag` as the default scheme. ## Creating a Classification Node You can create a Classification node as follows ```bash curl --request POST 'https://sandbox.meeco.me/vault/classification_nodes' \ -H "authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ --data \ '{ "classification_node": { "classification_scheme_name": "tag", "name": "my-new-tag", "label": "My Tag", "description": "Hi There this is my Tag!" } }' ``` [API Docs](https://dev.meeco.me/api-details#api=meeco-vault-api\&operation=post-classification_nodes) ```json { "classification_node": { "id": "b4ff857f-6f50-4608-bd93-b61a7dd012d5", "background_color": null, "description": "Hi There this is my Tag!", "image": null, "label": "My Tag", "name": "my-new-tag", "ordinal": 0, "scheme": "tag" } } ``` Properties `classification_scheme_name` and either `name` or `label` are mandatory. As mentioned above, `classification_scheme_name` should usually be 'tag'. As for other Vault objects, if only `label` is given, then the name is created by translating the label text. Since `name` is used to link a Classification Node to a Vault object, it must be unique. Note that currently, as for Item Templates, the API does not allow: * updating Classification Nodes, * deleting Classification Nodes, * sharing new Classification Nodes ## Applying Classifications Classification Nodes can be applied to Item Templates, Items and Slots. Most provide a way of creating new Classification Nodes in the same request. ### Templates Single Classification Nodes may be applied to Item Templates: ```bash curl --request POST 'https://sandbox.meeco.me/item_templates' \ -H "authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ --data \ '{ "label": "Some Template", "classification_scheme_name": "tag", "classification_node_name": "new_node", "slots_attributes": [] }' ``` Note that both `classification_scheme_name` and `classification_node_name` are required, and both must exist. Result ```json { "item_template": { "id": "78724525-9aed-4156-90c5-447198aa818b", "name": "some_template", "description": null, "ordinal": 0, "visible": true, "user_id": "e414dc7a-b6f1-4fb6-9481-41d7be5c8785", "updated_at": "2020-10-07T04:13:01.305Z", "label": "Some Template", "slot_ids": [], "classification_node_ids": [ "15ab7625-11f5-4518-99eb-e985c24414ad" ], "background_color": null, "image": null }, "slots": [], "classification_nodes": [ { "id": "15ab7625-11f5-4518-99eb-e985c24414ad", "background_color": null, "description": null, "image": null, "label": "New Tag", "name": "new_tag", "ordinal": 0, "scheme": "tag" } ], "attachments": [], "thumbnails": [] } ``` This has two effects. First, the Item Template can be found via its Classification Node or Scheme name, e.g. queries `GET /vault/item_templates?by_classification=tag`, or `GET /vault/item_templates?by_classification=new_tag` should include the template. Second, new Items created with the Item Template will be classified with the Classification Node. ```bash curl --request POST "https://sandbox.meeco.me/vault/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "Fun example", "slots_attributes": [ { "name": "bar" } ] }, "template_name": "some_template" }' ``` ```json { "item": { "id": "658ca227-b61b-4ce0-846d-baaf4cc17880", "name": "fun_example", "label": "Fun example", "description": null, "created_at": "2020-10-07T04:13:52.430Z", "item_template_id": "78724525-9aed-4156-90c5-447198aa818b", "classification_node_ids": [ "15ab7625-11f5-4518-99eb-e985c24414ad" ], "association_ids": [], "associations_to_ids": [], "slot_ids": [ "932e1f7e-10b5-4658-95b8-d5dff164bf37" ], "own": true, "...": "..." }, "associations": [], "associations_to": [], "classification_nodes": [ { "id": "15ab7625-11f5-4518-99eb-e985c24414ad", "background_color": null, "description": null, "image": null, "label": "New Tag", "name": "new_tag", "ordinal": 0, "scheme": "tag" } ], "slots": [ { "id": "932e1f7e-10b5-4658-95b8-d5dff164bf37", "name": "bar", "classification_node_ids": [], "item_id": "658ca227-b61b-4ce0-846d-baaf4cc17880", "...": "..." } ], "attachments": [], "thumbnails": [] } ``` ### Items Classification nodes are added to Items by passing `classification_nodes_attributes`, just like adding Slots. If the name and scheme match an existing Classification Node, it is used, otherwise a new one is created. Classification Node can be applied to both the Item and the Slots it contains. Unlike Item Templates, Items may have multiple classifications. ```bash curl --request POST "https://sandbox.meeco.me/vault/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "item class", "classification_nodes_attributes": [ { "name": "my_new_tag", "scheme": "tag" } ], "slots_attributes": [] }, "template_name": "some_template" }' ``` ```json { "item": { "id": "ff04474c-f661-4f71-b5a3-c40452c30e3b", "name": "item_class", "label": "item class", "description": null, "created_at": "2020-10-07T04:55:54.953Z", "item_template_id": "01bbb6a4-7466-423f-afdb-2d2f314011c4", "ordinal": 1, "visible": true, "updated_at": "2020-10-07T04:55:54.987Z", "item_template_label": "Some Template", "owner_id": "e414dc7a-b6f1-4fb6-9481-41d7be5c8785", "share_id": null, "classification_node_ids": [ "a9b7b318-2e22-4969-a521-e6d43d882bf6" ], "association_ids": [], "associations_to_ids": [], "slot_ids": [], "own": true, "...": "..." }, "associations": [], "associations_to": [], "classification_nodes": [ { "id": "a9b7b318-2e22-4969-a521-e6d43d882bf6", "background_color": null, "description": "Hi There this is my Tag!", "image": null, "label": "My New Tag", "name": "my_new_tag", "ordinal": 0, "scheme": "tag" } ], "slots": [], "attachments": [], "thumbnails": [] } ``` Note that even if the Classification Node `name` property matches an existing Node, but other fields don't, then a new Classification Node will be created. The `scheme` property must match an existing Scheme. Classification Nodes can be added to Slots too: ```bash curl --request POST "https://sandbox.meeco.me/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "Another Item", "slots_attributes": [ { "name": "new_slot", "description": "Some Slot", "slot_type_name": "key_value", "label": "New Slot", "classification_nodes_attributes": [ { "label": "A New Tag", "description": "Tag For The Slot", "scheme": "tag" }, { "name": "my_new_tag", "scheme": "tag" } ] } ] }, "template_name": "some_template" }' ``` In this case the `new_slot` receives both an existing Classification Node and a new one. ```json { "item": { "id": "bfa4c439-fc34-41e6-aba2-12191061ccb2", "name": "another_item", "label": "Another Item", "description": null, "created_at": "2020-10-07T05:15:42.039Z", "item_template_id": "01bbb6a4-7466-423f-afdb-2d2f314011c4", "ordinal": 1, "updated_at": "2020-10-07T05:15:42.131Z", "item_template_label": "Some Template", "owner_id": "e414dc7a-b6f1-4fb6-9481-41d7be5c8785", "classification_node_ids": [], "association_ids": [], "associations_to_ids": [], "slot_ids": [ "636faed0-11f2-4cc4-876e-9ce1118381c8" ], "own": true, "...": "..." }, "associations": [], "associations_to": [], "classification_nodes": [ { "id": "ec6a92a2-5578-49cf-b7de-23f7a7cf8081", "background_color": null, "description": "Tag For The Slot", "image": null, "label": "A New Tag", "name": "a_new_tag", "ordinal": 0, "scheme": "tag" }, { "id": "8ca80da9-53fa-4762-9b3b-857153f2dea0", "background_color": null, "description": null, "image": null, "label": "My new tag", "name": "my_new_tag", "ordinal": 0, "scheme": "tag" } ], "slots": [ { "id": "636faed0-11f2-4cc4-876e-9ce1118381c8", "name": "new_slot", "description": "Some Slot", "classification_node_ids": [ "ec6a92a2-5578-49cf-b7de-23f7a7cf8081", "8ca80da9-53fa-4762-9b3b-857153f2dea0" ], "item_id": "bfa4c439-fc34-41e6-aba2-12191061ccb2", "slot_type_name": "key_value", "label": "New Slot", "...": "..." } ], "attachments": [], "thumbnails": [] } ``` ### Slots Slots are usually given Classification Nodes via `POST /vault/items`, but you can add a classification to an existing Slot using `PUT /vault/slots/{id}`. Slots cannot be searched by Classification Node or Scheme. Some Slots have the type `classification_node`. The intent is that the owning Item will be classified with that node. Usually this is done within an app. # Attachments ## Attaching a File to an Item Every `item` in the meeco vault has the capability of having multiple files attached to it. The attachments are always attached to the `item` via a `slot` with the `slot_type` `attachment`. Assuming you have created an item already (such as the one you may have created in the getting-started page) and have the `.item.config` file still, lets create another item with that same config so as not to conflict with other steps later on in this guide. ```bash meeco items:create -i .item-config.yaml -a .alice.yaml > .item2.yaml ``` the next step is to create an `attachment-config.yaml` file with the following content. ```yaml kind: FileAttachment metadata: item_id: e8670e6c-8a95-43ff-a8d1-08805f612250 # (target item id from .item2.yaml) spec: label: 'Secret test webm video' file: './test.webm' ``` Then run the cli command ```bash meeco items:attach-file -c attachment-config.yaml -a .alice.yaml > .attach-response.yaml ``` You will get a response in the `attach-response.yaml` file that looks like the following ```yaml attachment: id: fe9ef5ad-b29c-4b71-bb73-b14fd4b88dca content_type: video/webm filename: test.webm ... slots: - id: 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b attachment_id: fe9ef5ad-b29c-4b71-bb73-b14fd4b88dca slot_type_name: attachment item_id: e8670e6c-8a95-43ff-a8d1-08805f612250 label: My Secret File encrypted_value: Aes256Gcm.z-T6OnEB6ssmkQK4RcvtYHjh2rE5PregqflhZoVXq6w=.QUAAAAAFaXYADAAAAAAhvEHoJqo845AsORoFYXQAEAAAAACahlEdh5rJcKfnl0DtTiaBAmFkAAUAAABub25lAAA= ... item: id: e8670e6c-8a95-43ff-a8d1-08805f612250 label: Item Label slot_ids: - 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b ... ``` Note: The slot's `encrypted_value` in this case is a new encryption key which has been encrypted with the user's own private data encryption key. The reason the file gets encrypted with a new data encryption key instead of directly with the user's existing private data encryption key has to do with sharing. By using this method when sharing, instead of having to re-encrypt the whole file with another data encryption key the slot's `encrypted_value` can simply be decrypted then re-encrypted with the data encryption key used for sharing. ## Downloading the Attached File To download an attached file the CLI needs to know the item's id and the slot's id, this is so the CLI can decrypt the data encryption key from the encrypted\_value of the slot (as mentioned above). Both of these values can be found in the `.attach-response.yaml` file under `slots[0].id` and `slots[0].item_id`. To download run the following ```bash meeco items:get-attachment e8670e6c-8a95-43ff-a8d1-08805f612250 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b -o ./output/ -a .alice.yaml # meeco items:get-attachment -o -a ``` ## Sharing and receiving the attachment Sharing an attachment simply works the same way you would share any other slot. First you will need to have a connection to another user, see the directions in the "Connections and Sharing" page to set up a connection first. Assuming you have a connection set up already and have the second user's info in a .bob.yaml file... Run the command ```bash meeco shares:create-config -i .item2.yaml -f .alice.yaml -c .connection.yaml > share-config2.yaml # meeco shares:create-config -i -f .alice.yaml -c > share-config.yaml ``` To create the share config then to create the share itself ```bash meeco shares:create -c share-config2.yaml > .create-shares-response.yaml ``` You should see some output like the following in the `.create-shares-response.yaml` file. ```yaml shares: - id: d9b68c36-110f-4171-8d9c-6bd580eff32d owner_id: c1f2485d-fe8d-4de2-b45f-deee52931207 sender_id: c1f2485d-fe8d-4de2-b45f-deee52931207 recipient_id: ca14e3ae-d7c9-49fe-85ec-ac3306414803 public_key: "..." encrypted_dek: Rsa4096.H-V2A_GlAbA3InFwKbdPoDVheM0p7kDIGg7tAtlnrF9-CFHtpo7pgE7MKBoszEp5jAkKwOlffZvaYt0ustjKb3yKDB-VKSKdZgu8yCkfJVNe8tgs5JpoZqg41krVrhVcUTLz6AsSfEXhnlFwKWLgbghqa7ad3u6LIGVVOTs_6-SBeuyJaYHDDBEN_TTiVqbIE7TU6LIUFSp38rpPOc0AM15FGZWhWcupYsy5gSO_jAOneBNi-sie392LX1LDPYbXi5fn-MSsWDektrR4bN0WlXA0iptTC-YqIrOFif9DFHL5qD5fis4Hfee95FCCPLBEtNoPNqU5u6YcE1a2XVlwPTMmeOVYDhHzl0HvT63QVc-zxhHqs3Tcg1mZtgDNb55qbUtNF8IGA1oOjG8LD69eIYOR3aO-cUs-iZcsZ-H0E7IqwX-bdCvZlLzUP1KI5sO3tIj32d9dCUCkvIJDf0TmPvB9UmF1rdoGDkT2dGvyGMA2sFQDhURq3I-NIOi4kp85h3l3JRN0BPcW1VzYCwX4Cn0HhG2brojv_Z8-j1QpCmOI9NO9XzJiMNi1ACMv-mJaEY4cBxvKtviY3eNaLsn8u-YrzH2InEOqrX7V9M2ynajf2YdJWxqCxUMXF_vWHxK04C6EQB2tdQ7SVNFchdjsuAjX-ue_RGmZ0hMNOXFCYjg=.QQUAAAAA terms: null expires_at: null ... ``` to see the incoming shared item first make a request for items as bob run ```bash meeco items:list -a .bob.yaml ``` you will see something like the following as output ```yaml kind: Items spec: - id: fce07d6a-0c6d-4615-acef-46beee08bb5f share_id: d9b68c36-110f-4171-8d9c-6bd580eff32d own: false name: item_label label: Item Label slot_ids: - 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 me: false background_color: null original_id: e8670e6c-8a95-43ff-a8d1-08805f612250 owner_id: c1f2485d-fe8d-4de2-b45f-deee52931207 ... ``` Notice how the `share_id` matches the share output from the previous command. We can then request the item itself. ```bash meeco items:get fce07d6a-0c6d-4615-acef-46beee08bb5f -a .bob.yaml # meeco items:get -a .bob.yaml ``` Returning ```yaml kind: Item spec: id: fce07d6a-0c6d-4615-acef-46beee08bb5f own: false label: Item Label slot_ids: - 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 original_id: e8670e6c-8a95-43ff-a8d1-08805f612250 owner_id: c1f2485d-fe8d-4de2-b45f-deee52931207 share_id: d9b68c36-110f-4171-8d9c-6bd580eff32d ... slots: - id: 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 own: false share_id: d9b68c36-110f-4171-8d9c-6bd580eff32d attachment_id: 4ac61cad-7911-46e9-a9f8-659b1eb79fc6 item_id: fce07d6a-0c6d-4615-acef-46beee08bb5f encrypted_value: Aes256Gcm.FYteKXIcTkjnC4OpqVcNFSzu5xwI3Eol0IubZUDpOhk=.QUAAAAAFaXYADAAAAACRE4YnWzELWDMfmE0FYXQAEAAAAACJtfJh93-EI7igsedpZ39aAmFkAAUAAABub25lAAA= label: My Secret File original_id: 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b value: "´ž\x10¹(MKnCȏ«BêSD\x01ˆ¾†]V*Ç\x16qøÀ¡^ó" ... thumbnails: [] attachments: - id: 4ac61cad-7911-46e9-a9f8-659b1eb79fc6 content_type: video/webm filename: test.webm ... ``` Now we have all the information we need to be able to download the attached file ```bash meeco items:get-attachment fce07d6a-0c6d-4615-acef-46beee08bb5f 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 -a .bob.yaml -o ./output/ # meeco items:get-attachment -a -o ``` ## Using the file-storage-browser or file-storage-node Packages The above flow is a great start to understanding how everything works however for actual product implementation these npm packages are likely to be more useful so please head to the following links and check out the README.md files there. file-storage-browser\ file-storage-node\ # On-sharing & Client Tasks ## Share Terms When sharing an item, a block of text can be added to the share, there is no required structure for these terms but something like the following should give you some idea of how it might be used. > I have allowed on-sharing on this item but before any on-sharing takes place call me on my phone to confirm it with me. or > This information on this item is being shared for the express purpose of applying for a home loan, it is not to be shared with anyone for the purposes of marketing or analysis. or > This information contains non-public business information and is for the eyes of Anthony Edward Stark only. ## Share Acceptance When creating a share there is an option to set whether acceptance of the terms and share is required, the settings allowed are `acceptance_required` and `acceptance_not_required`. Before the recipient of the share can view the data they must explicitly accept the share and it's terms via a second API call. For convenience when using the cli we have automatically set this feild to `acceptance_required` when any terms are specified. ## Sharing Mode When a user shares an item with another user there is an option to allow or dis-allow sharing of that item with another person, this is called the "sharing mode". The sharing mode currently has two options available on it, either `owner` or `anyone`. The `owner` sharing mode means the share can not be on-shared to another user. The `anyone` option means that the item can be on-shared to anyone. While the system will allow any on-sharing to happen when the sharing mode is set to `anyone` it is also important to check the `terms` that have set on the share. For convenience in the cli we have added the flag `--onshare` which will set the `sharing_mode` to `anyone` if it is present and set it to `owner` if it is not present. ## Client Tasks Due to use of e2e (end to end) encryption the client (client application) is the only place where data can be decrypted and re-encrypted. Sometimes there are tasks that do not need to happen right away when an action takes place but they will need to be done on the client at some point. An example of this is updating shares, for example... If a Alice has shared an item with Bob and some time later Alice changes the data in the shared item the share will also need to be updated.\ The data in Alice's items is encrypted with a DEK (data encryption key) that only Alice has access to, this means the server can not re-encrypt the data with a shared DEK on behalf of Alice, instead the server creates a `ClientTask`.\ Periodically Alice's client will check to see if there are any `ClientTask`s that need to be executed.\ Alice's client will pick up the `ClientTask` of type `update_shares` which will tell it to download and decrypt the modified item then re-encrypt the data with a shared DEK and update the share with the new data. ## Example of On-sharing and Executing Client Tasks (it's recommended to complete the getting-started/quickstart guide before follwing this example) (NOTE: each user will see the shared item as different `item_id`, when referencing the item by id be sure to use the `item_id` applicable to the user making the request) First lets create three users. ```bash meeco users:create -p supersecretpassword > .alice.yaml meeco users:create -p supersecretpassword > .bob.yaml meeco users:create -p supersecretpassword > .carlos.yaml ``` Next lets connect Alice to Bob, then Bob to Carlos. ```bash meeco connections:create-config --from .alice.yaml --to .bob.yaml > .connection1_config.yaml meeco connections:create -c .connection1_config.yaml > .connection1.yaml meeco connections:create-config --from .bob.yaml --to .carlos.yaml > .connection2_config.yaml meeco connections:create -c .connection2_config.yaml > .connection2.yaml ``` We create an item for Alice. ```bash meeco items:create-config vehicle -a .alice.yaml > .vehicle_config.yaml # open up the .vehicle.yaml and add an item label and other data meeco items:create -i .vehicle_config.yaml -a .alice.yaml > .vehicle.yaml ``` Share that item from Alice to Bob, with some share `terms`, `acceptance_required`, and sharing mode of `anyone`. ```bash meeco shares:create-config -i .vehicle.yaml -f .alice.yaml -c .connection1.yaml > .share1-config.yaml meeco shares:create \ --config .share1-config.yaml \ --onshare \ --terms="You may not use this information for advertising" \ > .share1.yaml ``` Read the share as Bob. ```bash meeco items:list -a .bob.yaml ``` You will get a result something like the following... ```yaml kind: Items spec: - id: 8e26d96f-7c15-444d-97a5-30e39b418c9d own: false label: DeLorean description: null created_at: 2020-10-12T05:52:45.395Z item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0 item_template_label: Vehicle slot_ids: - 642ea490-ccce-49cc-9fef-d5d9c6668549 ... me: false background_color: null original_id: dc66140c-3572-49b8-ad97-ec6de21827ba owner_id: 94c27129-e179-4c69-a7f1-94438b920541 share_id: b358bc99-89f1-48f3-8b84-8dad0516643e ... ``` Note the share\_id from above. Bob can have a look at the details and specifically the `terms` of the share by getting the share's details with the command. ```bash meeco shares:get-incoming -a .bob.yaml $EXISTING_SHARE_ID ``` Note that the item slot details are not available to Bob until he accepts the share and it's terms. Next Bob will accept the share from Alice. ```bash meeco shares:accept -y $EXISTING_SHARE_ID -a .bob.yaml ``` Bob can now pull down the item's details. (Note: the item id must come from the item when performing the items:list command, the item\_id in the shares:accept command will not work). ```bash meeco items:get 8e26d96f-7c15-444d-97a5-30e39b418c9d -a .bob.yaml > .shared-to-bob-item.yaml # meeco items:get -a ``` Now Bob can share this item with Carlos. ```bash meeco shares:create-config -i .shared-to-bob-item.yaml -f .bob.yaml -c .connection2.yaml > .share2-config.yaml meeco shares:create \ --config .share2-config.yaml \ --terms="You may not use this information for advertising" \ > .share2.yaml ``` Carlos can now see the share. ```bash meeco items:list -a .carlos.yaml ``` Returning something like... ```yaml kind: Items spec: - id: 59cb375f-6188-46fd-bdd6-ba730ae3282c own: false label: DeLorean description: null created_at: 2020-10-13T05:41:02.376Z item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0 item_template_label: Vehicle slot_ids: - e90e38f2-65d7-4203-b74f-0831dab393c1 ... original_id: dc66140c-3572-49b8-ad97-ec6de21827ba owner_id: 94c27129-e179-4c69-a7f1-94438b920541 share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c ``` Noting the share\_id and item\_id from the above command. Accept it. ```bash meeco shares:accept $EXISTING_SHARE2_ID -a .carlos.yaml ``` And view it. ```bash meeco shares:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yaml # or meeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml ``` Getting the output something like... ```yaml kind: Item spec: id: 59cb375f-6188-46fd-bdd6-ba730ae3282c own: false label: DeLorean item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0 item_template_label: Vehicle slot_ids: - 81cc655f-5ae8-4a7a-afc0-3d186ab3f736 ... me: false background_color: null original_id: dc66140c-3572-49b8-ad97-ec6de21827ba owner_id: 94c27129-e179-4c69-a7f1-94438b920541 share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c slots: - id: 81cc655f-5ae8-4a7a-afc0-3d186ab3f736 own: false share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c name: licence_plate item_id: 59cb375f-6188-46fd-bdd6-ba730ae3282c slot_type_name: key_value encrypted_value: Aes256Gcm.AjR9r_An-mcqLla1dcGL.QUAAAAAFaXYADAAAAACcR_n2XVORiZ2wRjgFYXQAEAAAAACCNE5L6Gqq-4Zmm5Y8AgVEAmFkAAUAAABub25lAAA= encrypted_value_verification_key: Aes256Gcm.f4af1rELcDkDJQv7wPsfvOOVbnI6YyQlsnYLdDdekAZ2AcXm6Oq7WrgGytc3gUbvjnWvmkzAnWO2s2Kya0ZxLQ==.QUAAAAAFaXYADAAAAABQ346yXewWcSdSdBEFYXQAEAAAAACyZph19u-eZ-BWMPhrOqP4AmFkAAUAAABub25lAAA= value_verification_hash: d8c6e5f28837906505fa9e6a4740c8ddd5dddbe4b51675ae3daabef4a27d701b label: Vehicle registration number original_id: 5503d256-19d6-45f8-b76b-9605f977cd3f owner_id: 94c27129-e179-4c69-a7f1-94438b920541 value: NotACatDefsACar value_verification_key: "5ÁÑ\x1a”=Ù¯\a\a\x1f|1\v§ì¨Nqe¡b\x05Ç\rr’v—ý[nê\x05À\x11ޜBïǚí\eé\x14y\ há_éû›Cz)žêö\0ۊ]³" ... ... thumbnails: [] attachments: [] ... ``` So now we have an Item on-shared from Alice to Bob to Carlos. What if Alice now wants to update the item and get Bob and Carlos the updated data? First Alice updates the item. ```bash meeco items:get $VEHICLE_ITEM_ID -a .alice.yaml > .existing_vehicle_item.yaml # edit the .existing_vehicle_item.yaml file, specifically the `value` fields of the `slots` and/or the `label` field of the `item` then... meeco items:update -i .existing_vehicle_item.yaml -a .alice.yaml ``` Ok, the item has been updated at this stage but not the shares. Note that the last line of the `items:update` command showed a comment saying ```bash # Item updated. There are 1 outstanding client tasks. Todo: 1 & InProgress: 0 ``` If we request the list of Client tasks with the following command... ```bash meeco client-task-queue:list -a .alice.yaml ``` We will see a list of ClientTasks that are outstanding something like the following. ```yaml kind: ClientTaskQueue spec: - id: 0de4fb1a-6c43-4ca5-8880-c5187df3972b state: todo work_type: update_item_shares target_id: dc66140c-3572-49b8-ad97-ec6de21827ba additional_options: {} last_state_transition_at: null report: {} created_at: 2020-10-13T06:02:55.028Z ``` What we need to do next is re-encrypt all the new data with a new DEK to share with both Bob and Carlos. We can do this by running the command. ```bash meeco client-task-queue:run-batch -a .alice.yaml ``` You will see the output something like the following. ```yaml completedTasks: - id: 0de4fb1a-6c43-4ca5-8880-c5187df3972b state: todo work_type: update_item_shares target_id: dc66140c-3572-49b8-ad97-ec6de21827ba additional_options: {} last_state_transition_at: null report: {} created_at: 2020-10-13T06:02:55.028Z failedTasks: [] ``` Now Carlos and Bob have the updated shared data, you can check that by running the commands. ```bash meeco shares:get-incoming $BOB_SHARED_INCOMING_SHARE_ID -a .carlos.yaml or meeco items:get $BOB_SHARED_INCOMING_ITEM_ID -a .bob.yaml meeco shares:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yaml or meeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml ``` Hopefully this guide has given you a decent high level overview of how the process works.\ To dig further into the functionality why not try checking out how the CLI () uses the underlying SDK (). # Account Delegation ## What is account delegation Account delegation provides access and/or control over your private encrypted data to another user. The intended purpose for this feature is to allow people you trust full access. In almost all cases we recommend using Shares and On-Shares to give access to other users as it gives much more granular control over the data shared to another user. An example where you might use a feature like this is where a user is helping a family member (be that a child or an elderly parent) who requires assistance. ## Setting up delegation ### Setting up the Scenario First lets create two new users to set up a delegation between. ```bash meeco users:create -p password > .riker.yaml meeco users:create -p password > .homer.yaml ``` Next lets create an item in Riker's account so we can later test to make sure Homer has access to it. ```bash # List out available templates meeco templates:list -a .riker.yaml # Create an item config file from one of the chosen templates meeco items:create-config vehicle -a .riker.yaml > .riker-vehicle-config.yaml # Extra step, open up the above item config yaml file and modify it in your chosen text editor # Create the item using the above item config yaml meeco items:create -i .riker-vehicle-config.yaml -a .riker.yaml > .riker-vehicle.yaml ``` ### Creating the Delegation Connection Next lets get Riker to create a delegation connection invitation with the delegation role `reader`. (delegation-role options are `owner`, `admin`, and `reader`) ```bash meeco delegations:create-invitation -a .riker.yaml Homer reader > .delegation-invitation.yaml ``` Homer can now accept that delegation connection invitation from Riker and the delegation connection will have been created. ```bash meeco delegations:accept-invitation -a .homer.yaml -c .delegation-invitation.yaml Riker > .delegation-connection.yaml ``` ### Sharing the Key Encryption Key While the connection has been created There are still a couple more steps to go before the delegation has been fully set up. These steps are for sharing Riker's Key Encryption Key (KEK) to Homer. First Riker must Encrypt his KEK with Homer's public key and send it. ```bash # meeco delegations:share-kek -a .riker.yaml meeco delegations:share-kek 53cbd900-6657-40a0-9fae-ad8ac20078f4 -a .riker.yaml ``` Next Homer accepts Riker's KEK, decrypting it with his private key, then storing it for access later under his own KEK. ```bash # meeco delegations:accept-kek -a .homer.yaml meeco delegations:accept-kek 099ebb9b-b49f-4c20-8606-b92b7dcc8ea6 -a .homer.yaml ``` ### Reading User data as a delegate user First Homer can pre-load Riker's KEK and Private DEK should for decrypting the data. ```bash # meeco delegations:load-auth-config --delegationId -a .homer.yaml > .homer-with-riker-delegation.yaml meeco delegations:load-auth-config --delegationId c0181886-20de-45de-b4b5-b614f92f2440 -a .homer.yaml > .homer-with-riker-delegation.yaml ``` Next Homer can list out the Riker's items. ```bash # meeco items:list --delegationId -a .homer.yaml meeco items:list --delegationId c0181886-20de-45de-b4b5-b614f92f2440 -a .homer-with-riker-delegation.yaml ``` Then, taking note of the item id from the items:list command, finally Homer can view the item Riker created earlier. ```bash # meeco items:get --delegationId -a .homer-with-riker-delegation.yaml meeco items:get --delegationId c0181886-20de-45de-b4b5-b614f92f2440 0f0dc0d3-d7f4-42e6-8b46-e41bf3a51d2a -a .homer-with-riker-delegation.yaml ``` # Meeco SDK & CLI We have created the [Meeco SDK](https://www.npmjs.com/package/@meeco/sdk) and the [Meeco CLI](https://github.com/Meeco/js-sdk/tree/master/packages/cli). ## SDK {% embed url="" %} Our first release of the SDK is written in Typescript, and we have it released as an [NPM Package here](https://www.npmjs.com/package/@meeco/sdk) so you can easily import our modules into your project and start making calls to our APIs. For full usage and functionality, you can visit the [API Docs](https://meeco.github.io/js-sdk/). ### SDK in other languages Whilst the SDK is currently only available in Typescript/Javascript, we are in the process of creating the SDK in other languages: * Java * Swift * Dart If you would like a port of the Meeco SDK in another language, let us know through the [Meeco.me contact page](https://www.meeco.me/contact) with "Developer Portal" set as the Enquiry Type. ## CLI ### A tool for interacting with Meeco services and databases {% embed url="" %} To get the Meeco platform up and running so that you can get a feel for it as a developer, we have created some tools that set up a Meeco User and create all the necessary access tokens and keys for you to explore what Meeco can do. In short, it can: * Create Users * Connect Users * Create Items and Templates * Share Items between Connected Users * Create and Manage Organisations You can use the keys and tokens that the Meeco CLI has generated in combination with the [Cryppo-CLI](/latest/tools/cryppo) tool to get a feel for the encryption and decryption flows. Feed this data back to the Meeco-CLI to store it against a Meeco User and then Share it! You can read more about [Sharing and Connections](https://github.com/Meeco/docs/blob/archive/2022-01/guides/connections-and-sharing.md) and [Items](https://github.com/Meeco/docs/blob/archive/2022-01/guides/items-and-slots.md) in the Guides section of this documentation site. The Typescript CLI and SDK Github repos reside below in the downloads section. The CLI documentation can be found below - it will help you set up tool so you can begin making requests against our APIs. {% embed url="" %} The Typescript SDK documentation can be found below {% embed url="" %} The CLI relies heavily on the SDK, so by running through the commands we've got set up, you'll be able to follow along and learn how the Meeco Platform works, and give you some idea about what it can do. ### What Next? Now, go back to the [Meeco Quickstart](/latest/getting-started/quickstart) guide and follow the run-through in order to create a User, setup the Keystore, gain access to the Vault and create your first Item! # Cryppo SDK & CLI Meeco's encryption libraries to make encrypting and decrypting data in the API-of-Me easy ## Cryppo SDK Cryppo is a cryptographic library that helps you encrypt and decrypt data in way that is compatible with Meeco's recommended serialization and encryption formats. It comes in different flavours but you can re-implement the routines in whatever Language you like. Feel like using Flutter? Write the library in Dart! Cryptography is hard, and the Cryppo libraries do all the heavy lifting in the creation of cryptographic key pairs, encrypting and decrypting data, and make it trivial to serialize the encrypted data in a way that makes it easy to store and retrieve from the Meeco Vault. The library is available for the following platforms | Language | URL | | ---------- | -------------------------------------- | | Elixir | | | Javascript | | | Ruby | | We'll be using the libraries to run through some of the more in-depth examples on this documentation site, so choose your preferred language and follow along. ## Cryppo CLI We've also created a simple CLI for Cryppo called `cryppo-cli` which can be found at: {% embed url="" %} With the Cryppo CLI you can use the following functions: * Encrypt a value * Decrypt a value * Generate a url-safe base64 key of variable length (see [DEK](https://docs.meeco.me/guides/terminology#data-encryption-key-dek)) * Generate an RSA keypair * Sign a file with an RSA private key * Verify a file that has been signed with an RSA key # Privacy Here at Meeco, we take your privacy seriously. Read our complete [Privacy Policy on our Company site ](https://blog.meeco.me/privacy-policy/)which covers cookies, your data, our obligations to you and more # Developer Policy What you need to know about using our sandbox APIs ## Developer Policy Please read this policy to understand Meeco’s terms and conditions for the use of our APIs in the Developer Sandbox Environment at . ### Sign Up * Signing up allows you to create Subscription Keys which are used to authenticate you in all Sandbox API calls. * Without active subscription keys it is not possible to use the portal to receive the correct responses from the Meeco Sandbox APIs. * You must provide accurate information about you and your organization while registering. By signing up to the Meeco portal you agree to our terms and conditions and usage restrictions contained therein. ### System Availability & API Upgrade * We are committed to ensure uninterrupted availability and performance of our services and try our best to minimize downtime. Meeco will perform system upgrade/maintenance as and when required and is not liable for any inconvenience/loss occurred due to unavailability of our Sandbox services. ### ### Security * The various tiers of subscription limit the amount and frequency of calls you can make in the Sandbox environment. * You must safeguard the API keys and username/password information and never share this information with any other person/organization. ### Usage Restrictions You must not: * Spam, overload or flood the system * Use the system to store/distribute any offensive, illegal, fraudulent or abusive material * Transfer or distribute services without our permission * Use our service for any purpose that violates any applicable law, statute, ordinance, or regulation, especially laws that deal with financial data, data protection, privacy and data security. * Use the Meeco services to capture and decrypt the personal data of users of their app, nor store any of their data * Sell or rent any user data to marketers or third parties * Access or use the service for any unlawful, infringing, threatening, abusive, obscene, harassing, defamatory, deceptive, or fraudulent purpose * Scan or test in any method the potential vulnerability of any Meeco infrastructure * Breach, disable, interfere with, or otherwise circumvent any security or authentication measures or any other aspect of the Meeco platform * Decipher, decompile, disassemble, copy, reverse engineer, or attempt to derive any source code or underlying ideas or algorithms of any part of the Meeco Platform, except as permitted by applicable law; * Modify, translate, or otherwise create derivative works of any part of the Meeco Platform * Claim to represent Meeco, such as claiming that the developed product is endorsed by Meeco Each subscription tier has differing quotas and request rate limiting. In addition, Developers must acknowledge the use of Meeco services in their product. ### Suspension & Termination * Meeco reserve the right to refuse or suspend access to the Service in whole or in part where we believe the Service is being accessed or used in violation of this Policy. * We will use reasonable efforts to notify you via email or other method when deciding to withhold, refuse, or terminate access to the Platform. * We may immediately suspend or terminate access without notice if appropriate under the circumstances, such as when we become aware of activity that is a violation of any applicable law or when we determine, in our sole discretion, that harm is imminent. * Meeco will not be liable for any damages of any nature suffered by you or any third party resulting from Meeco’s exercise of its rights under this Policy or under applicable law. * You may request that your account be deactivated by mailing ### Policy Violation Reporting * Please report at if you notice any violation of this policy. We may take any appropriate action -- including reporting any activity or conduct that we suspect violates the law to appropriate law enforcement officials, regulators, or other appropriate third parties -- in our sole discretion in respect to such violations. # Releases ## 2021-Q2 ### Vault v32.4.3 * Fixed delegate user role for to access user's DEK * Removed conversations and messages endpoints * Added client task for re-encrypting the account owners KEK during delegation setup * Added support multiple JWT issuers for OpenIDConnect Authentication flow. * Added support seamless identity transition on OpenIDConnect identity provider change. * This feature requires OpenIDConnect JWT to enclose a special claim `extension_meecoUserId` with value reference to the previous Meeco user identity. * Added parameters for `GET /connections`: * `delegation=granted_to_the_other_user`; the current user has granted delegation to other users * `delegation=granted_to_me`; the current user has received delegation from other users * Changed `GET /session` shows: * the type of the session (`oidc` or `token`) * if the type of the session is `token`, the access token will be shown * Added parameters to `GET /items`: it is now possible to fetch only items with a certain name via `?name=foo` * Added Share intents: * `POST /invitations/{invitation_id}/share_intents` to create a share intent * `DELETE /share_intents/:id`, * `GET /share_intents/:id` * `GET /share_intents` * Models `Invitation` and `PublicInvitation` have new field `shares_to_be_created` * response to `POST /connections` contains a new element: a report on the created connections * Changed parameters `valid_for` added to `POST /sessions`. `valid_for` defines the number of seconds the token is going to be valid * Changed handling of errors in `POST /items/shares`: field `extra_info` contains a subset of incoming parameters with the error. * Removed image and background color for the Item model (removed fields `image_background_colour`, `background_color` which are realted) * Removed Item flag `me` from items. * Changed User field `verified_at` so is hidden. * Removed legacy `messages` feature which was not being used and would need to be upgraded if it were to be used. * Changed the `POST /thumbnails` endpoint request structure to be nested under a `thumbnail` object * Fixed performance on the `POST /items` endpoint * Changed classification parameters for `POST /items` and `PUT /items` endpoints * Changed `POST /classification_nodes` to only be used for user managed schemes (tags) * Changed error messages on `POST /items` endpoint to provide more detailde cause * Added field `owned_by_user` to classification scheme * Removed `value` from POST /items, `encrypted_value` field should be used instead * Removed POST /images endpoint and all image relations on items and users, images (unencrypted) are now only to be used by system admins, this helps clear confusion and the risk of user's images being sent up unencrypted. * Removed associations from users and items * Added enum definitions to the swagger file (and generated sdk) for the following models: * `ClientTask.state` * `ClientTask.work_type` * `Event.eventable_type` * `Event.event_type` * `OwnConnectionData.connection_type` * `TheOtherConnectedUserData.connection_type` * `Service.status` * `Organization.status` * `Share.acceptance_required` * `Share.sharing_mode` * `OrganizationMember.role` * `User.user_type` * Removed updating of a slot in the `PUT /items` endpoint. You must now specifiy the slot's id to update it, any slot sent up without an id will be treated as a new slot * Changed the flow of downloading attachments so fewer API calls are needed (see newly released cli/sdk implementation for example usage) * Removed fields `is_app_logging_enabled`, `unconfirmed_email`, `share_terms` from model `User` * Removed UserAccessToken fields `name`, `device_push_token`, `push_token_platform` * Added `item_ids` parameter to retrieve multiple specific items at once. e.g. `GET /items?item_ids=abc,xyz,foo,bar` * Changed share objects to hide the `owner_id` field from share objects when the sharee is not connected with the owner of the item (e.g. on-share) * `POST /items` - added fields `name` and `description` to the list of accepted item fields * `POST /items`: removed fields `id` and `_destroy` from slot attributes when creating a new item. * Added documentation for `GET /images/:id` endpoint * Removed GET /attachments/:id/download from documentation (this endpoint had already be decommisioned in the previous release) * `attachment_id` in slots no longer changes when sharing a slot with an attachment * Changed the shape of the nested attachment json (on POST /items etc) * Removed `slots.attachment_uid` as `attachment_id` does not change upon share now. * Changed behaviour of attachements to enforce data integrity * once a slot has an attachment, it is not permitted to remove or replace the attachment * once a slot has an attachments folder, it is not permitted to remove or replace the attachments folder * Changed the urls generated by the server for images and thumbnails. Redirects are now handled by 2 endpoints: * `GET /blobs/public/{id}/{digest}` - for images and thumbnails * `GET /blobs/attachment/{id}/{digest}` - for attachments and direct attachments * Removed `PUT /slots/:id`. Instead, `PUT /items/:id` should be used. * Added attachment folders functionality; managing attachments folders not linked to any slots: * `POST /attachments_folders` * `GET /attachments_folders` * `GET /attachments_folders/:id` * `DELETE /attachments_folders/:id` * Added attachments folders for slots: * To attach an existing attachments folder use property `attachments_folder_id`, see model `NestedSlotAttributes` * To access a attachments folders data use `GET /slots/:slot_id/attachments_folder` * Added new parameters for `GET /items`: * `own` boolean, if true adds constraint `items.user_id = items.owner_id`, if false adds constraint `items.user_id != items.owner_id` * `owner_id`, if present, adds constraint `items.owner_id = 'parameter goes here'` * Removed Field `encrypted` in `Slot` * Removed fields `cloudname`, `key_store_admission_token`, `key_store_id`, `key_store_url`, `key_store_username` in `User` ### KeyStore API v5.8.1 * Added support multiple JWT issuers for OpenIDConnect Authentication flow. * Added support seamless identity transition on OpenIDConnect identity provider change. * This feature requires OpenIDConnect JWT to enclose a special claim `extension_meecoUserId` with value reference to the previous Meeco user identity. * Changed `GET /session` shows the validity of the current session * Added endpoint `POST /session/limited_in_time` * Added new parameters `valid_for` added to `POST /sessions`, `POST /sessions/with_login_key`, and `POST /srp/sessions`. `valid_for` defines the number of seconds the token is going to be valid * Fixed Authorizations in the swagger file (userAuthToken, oidc2UserAuthToken, subscriptionKey, meecoDelegationId]) * Added new mandatory parameter in `POST /child_users`: `delegation_token` * Added `private_dek_external_id` to the response of `POST /child_users` ### StyleKit v2.0.0 * Version bump on most dependencies * Build directory now fonts and images ### SDK v3.0.0 * Version bump on most dependencies ### FileStorageBrowser, FileStorageNode v5.0.0 * Version bump on most dependencies ### CLI v3.0.0 * Version bump on most dependencies ## Feb 2021 ### CLI v2.0.0 * `users:get` renamed to `users:login`, has the effect of recreating tokens if expired. * `users:get` now returns user's id and other user info. * `shares:create-config` takes connection and item config files (output of `connections:create` and `items:create`) instead of the respective ids. * `client-task-queue:list` no longer accepts `--suppressChangingState`, pass `--update` if you want to set listed tasks to `in_progress`. * `client-task-queue:run-batch` can now run `failed` tasks too. * new command `client-task-queue:update` allows changing status of client tasks. * `client-task-queue` commands now have `--limit` parameter * added `items:create-thumbnail` * `meeco items:list` allow filtering list by `templateId`, `scheme`, `classification` and `sharedWith`. * added `oidc_token` OIDC token header support for authenticating user. ### SDK v2.0.0 * Major revamp of Services API: * All custom service methods specify the required credentials by interfaces * Services provide their base APIs via the `getAPI` method * Services with paginated responses offer a `listAll` method * Added Service for delegating child users * Added cryppo wrapper classes `SymmetricKey` and `PublicKey` to simplify key usage within SDK * Added classes for manipulating Items and Slots: `DecryptedItem` for client-side copies, `NewItem` and `ItemUpdate` for pending changes. * Added demo app for sharing and delegation * added `oidc_token` OIDC token header support for authenticating user. ### Vault API v19.3.0 * Add user\_public\_key to response of `GET /invitations/{:token}` * Remove `child_public_key_for_login` parameter from `POST /child_users` * Update description of `sharing_mode` in `POST /items/{id}/shares` * New field `item_shared_via_another_share_id` in ShareWithItemData If this field is NULL it means that the rendered item has been created via the currently displayed share. If `item_shared_via_another_share_id` is not NULL, it means that the rendered item has been created via a different share, and the ID if the share is in `item_shared_via_another_share_id`. The client is advised to re-run the call with this ID. * Change default behaviour of `GET /client-task-queue` to not change task states `supress_changing_state` parameter has been changed to change\_state to reflect the change. * Add delegation\_token parameter description in `POST /invitations` * Change behavour of GET /client\_task\_queue * Will now return items of all states by default * Accepts a list of states instead of a single state as before * Generated TypeScript client will now require that states are passed using the generated ClientTaskQueueGetStateEnum enum * Removed logging in with a password `POST /session/login` * Add item\_ids query parameter for `GET /outgoing_shares` as search filter. * Support for OIDC2 * Added filter target\_id to `GET /client_task_queue`: `GET /client_task_queue?target_id=id` * Add `GET /event_feed endpoint` * Swagger models `Slot`, `Attachment`, and `DirectAttachment` all have a new field: `attachment_uid`. The function of `attachment_uid` is to signal whether the actual file referenced from two different attachments is the same or not. In other words, when an attachment is shared to a different user, a new attachment record is created with a new id, but `attachment_uid` stays the same. This ID cannot be used to retrieve the attachment. * added filter `classification_node_names` to `GET /items: GET /items?classification_node_names=value_1,value_2,value_3` * added filter `shared_with` to `GET /items: GET /items?shared_with=user_id`. 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. ### KeyStore API v5.1.0 * Add `POST /child_users` endpoint * Add `POST /delegations` endpoint * Add `GET`, `DELETE /delegations/:delegation_token` endpoint * Add `PUT /delegations/:delegation_token/share` endpoint * Add `PUT /delegations/:delegation_token/reencrypt` endpoint * Rename `DELETE /session/all` :delete\_all\_session\_params query param to :except\_current of boolean type. * Add `POST /delegations/:delegation_token/claim` endpoint * Added user delegation header `Meeco-Delegation-Id`. `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` * Remove encryption spaces endpoints * Dropped support for `POST /keypairs/external_id/:external_id/` decrypt\_session\_token * Support for OIDC2 * External\_identitiers in Keypair is a string, not an object. * Private\_dek\_external\_id is added to the response of `POST /child_users` ### Cryppo/JS v2.0.0 * Breaking changes: * Encrypt method now accept bytes UInt8Array as input. * Decrypt method now produce bytes UInt8Array as output. * RSA signature also accept bytes UInt8Array as input. * Private key encryption also accepts bytes as input. ### File-Storage-Browser, File-Storage-Node v3.0.0 * Updated cryppo version 2.0.0 * Updated Vault-api-sdk: 19.X.X & keystore-api-sdk: 5.X.X ### Cryppo CLI v2.0.0 * No functional changes, updated new cryppo version 2.0.0 ## October 2020 ### Vault API v16.0.1 * On-sharing - the ability to allow other users to share an item that has been shared with you if the item’s owner allows it. This includes a verification step to make sure the on-sharer has not modified the data. * Organizations - you can now create an account for your organisation and add members and services. * Accepting of shares - we’ve identified that sometimes the terms of a share need to be reviewed and explicitly accepted or rejected before seeing the data so we’ve now made this possible. * More efficient file attachments, we now have the ability to receive encrypted chunks of data so an entire file doesn’t have to be encrypted as one before sending it up. * Improved Sharing - sharing is more streamlined, comprehensible and performant than ever before. * Sharing of encrypted files with other users. * Re-encrypting of shared data to cut down on the number of Encryption Keys needed to be stored/managed indefinitely. * Updated to use latest BSON serialization format from Cryppo. ### KeyStore API v3.0.0 * Remove the shared key endpoints as sharing keys for shares will now happen in the vault. * Removed the encryption\_spaces endpoints in favor of just using the Date Encryption Key endpoints. ### SDK v1.0.0 * Added Item Update function * Added Functions to Retrieve Client Tasks and Execute the Tasks. * Added some Organization related commands where the logic was not just a simple endpoint req * Exposed more methods from the user create and user login flow to allow more control from client applications. ### CLI v1.0.0 * Added Share Delete command. * Added Item Update function * Added Functions to Retrieve Client Tasks and Execute the Tasks. * Added Commands for Creating and Managing Organizations, Organization Services, and Organization Members. * Added Checking the Client Task Queue after updating an item to see if shares need to be updated. * Added user login and logout methods. ### Cryppo/JS v1.0.0 * Updated to return null when an empty string is passed in instead of returning a serialized empty string. * Updated to the latest underlying node-forge library. * Update to use BSON serialization. * Better handling of character encoding by forcing UTF-8 where appropriate. ### Cryppo/Ruby v1.0.0 * Update to use BSON serialization. * Added Checking of the Client Task Queue after updating an item to see if shares need to be updated. ### Cryppo CLI v1.0.1 * No functional changes, just updated to use new linked libraries. ### File-Storage-Browser, File-Storage-Node v2.0.0 * Initial release of these browser-js/node-js packages to upload files as chunks of encrypted data. ### Style-Kit v1.0.0 * Initial release of this html/js library used for adding Meeco’s stylings to your app or components of your app. # Docs This documentation serves as the primary source of information for individuals new to Meeco's Secure Value Exchange (SVX) platform. It explains the fundamental concepts of digital identity networks and highlights the specific role that SVX plays within this ecosystem. This documentation serves as an essential resource for users to grasp the core concepts and functionalities of SVX, empowering them to leverage its capabilities effectively. ## Concepts Deepen your understanding of digital identity concepts.
Digital IdentityDefining the core concept of the platform/pages/OJFL1a1eBMuBDFgDGb1j
Secure StorageProtect sensitive personal data/pages/nnW4dPdR69K7OmzSXCTx
Verifiable CredentialsOpen standard for asserting information about anything/pages/GUx7N5gHxoTeoTHAatFt
## Platform Embark on your journey and harness the full potential of the platform's capabilities.
Introducing SVXComposable platform to manage a data network/pages/BlolcyuoLdv1dGu5sTzE
VaultMeeco's secure, end-to-end encrypted, storage implementation/pages/KzQKKuTf5Y4cKiXVazeu
Credential ServiceIssue, present and verify credentials/pages/xVsNEaXpZHSPugGamJ9w
## Tools Build faster with the following tools.
SVX SDKJavascript SDK for faster development/pages/5Yl0PmWlYwccD3CBUuih
Meeco WalletExperience the mobile identity wallet in App Store and Play Store./pages/XNXmSKVGwF5J0Uwi8MCb
Cryppo SDKAiding in encryption and decryption/pages/RVxCMbJkFBo3HmC8Wjxm
## Environments SVX is available in both public deployment (hosted in Amsterdam, EU), as well as private deployments (contact us). In the public environment we currently have the following environments setup: * **sandbox**: allows you to experiment freely in an environment that is always updated to include the latest and the greatest functionalities. * **pre-production**: mimics the production environment, and allows you to perform regression tests. * **production**: where the rubber hits the road. # Digital Identity and Why It's Important Digital identity is the digital representation of an identifier (or a group of attributes), data and correlations to accurately describe a specific person, entity, or thing. A person’s digital identity is commonly used as a catch-all term to represent any personally identifiable information (PII) that can be used to identify someone’s civil, social or individual identity. As people upload more of their unencrypted and non-anonymised PII to the internet, it becomes easier for other digital users to undertake malicious acts such as identity fraud. When digital identity is managed within a trusted, authenticated ecosystem, all ecosystem parties can ensure that: * The identity subject (referred to as the Holder) is protected and cannot be compromised * The identity providers (referred to as Issuers) are delivering PII securely to the rightful Holder, and * The relying parties (referred to as Verifiers) can be assured that the PII they are verifying is from a trusted source and the claims associated with the Holder are true. Verifiers are also committed to only using the data for the contracted purpose. ## Identity models and approaches There are many digital identity models all of which can be used in different scenarios with different outcomes. Many models incorporate different digital identity approaches to streamline processes and/or further reach. Some of the most commonly referenced models and approaches are summarised below. ### Centralised identity The centralised identity model places service providers or centralised governments at its centre, with these organisation being the custodians of users' identity. Users are given accounts and login details in order to access their identity data but have limited control over ownership and data exchange. ### Federated identity When taking part in a federated identity model, a user can log in or access an identity provider (IDP) which communicates and shares their data with organisations on their behalf. In this model, a group of IDPs that the user can select from is called a federation, and the organisations that request an individual's identity data are called Relying Parties. ### Decentralised identity The decentralised identity model gives users complete control over their identity data. Their identity data is stored on a device of the user’s choosing, and exchanges of this data occur peer-to-peer. Rather than creating accounts and accessing external systems, users create connections with one another that can be managed by the users themselves. ### Self-sovereign identity Self-sovereign identity (SSI) is closely aligned with decentralised identity in that it supports the idea that the user is at the centre of the data ecosystem and each user controls and exchanges their data via peer-to-peer interactions. The additional layer that SSI brings is that it can be applied to all aspects of digital identity including the business, legal and social aspects. To achieve an ecosystem where trust filters through these different layers, resulting in all participants trusting each other, requires the implementation of governance frameworks. These frameworks are key for SSI infrastructure to be successful. ### Reusable identity Every time a user logs in to a platform or shares their PII there is a risk that their data could be shared with third parties or used for malicious intent. Reusable identity is an approach to securely storing users' credentials, login in information, and PII in a unified platform which can be accessed only by the user when they require it. This approach not only reduces the risk of data theft but saves the user time when completing sign up, login and other data exchange workflows. ## Trust A recurring theme when discussing digital identity is that of trust. As mentioned above, all parties within a digital identity ecosystem or workflow need to trust each other in order to manage a robust identity exchange network. To ensure different parties can trust each other, many governments and organisations are implementing standards and frameworks into their practices. These standards and frameworks create standardised rules and requirements for each ecosystem participant, making involvement in a digital identity network more reliable, ethical and risk-reducing. ### Trusted Digital Identity Framework (TDIF), Australia In Australia, the [Trusted Digital Identity Framework (TDIF)](https://architecture.digital.gov.au/trusted-digital-identity-framework-tdif-0) provides nationally recognised accreditation to digital identity, attribute, and credential service providers. This accreditation ensures that providers meet an extensive list of requirements, including privacy, security and risk management obligations when engaging with customer’s PII. The providers who obtain TDIF accreditation are providing digital identity solutions aligned with Australian Government built standards. # Digital Wallets Digital wallets enable users to manage their digital assets easily and securely from the device(s) of their choosing. Wallets are commonly used for the management of data and transactions, ranging from identity documentation (driver licences and certificates), financial (payments and transfers), tokens (fungible and non-fungible), and loyalty programs (vouchers and point accumulation). Wallets can be divided into two categories: single purpose or multi-purpose. Single purpose wallets focus on the management of one service, while multipurpose deliver a range of services that can be inter-linked or standalone. ## What is an Identity Wallet? An identity wallet focuses on the safeguarding and management of a wallet holder's (Holder) identity data. The wallet acts as a secure container that generates, stores and processes the Holder’s: 1. [Cryptographic keys](/svx-v3/platform/keys) 2. [Decentralised identifiers (DIDs)](/svx-v3/platform/did) 3. [Credentials](/svx-v3/concepts/verifiable-credentials) (e.g. W3C Verifiable Credentials, mDL, PDFs) A wallet also maintains the many connections its controller makes with other wallets. It is coupled with a software agent that utilises different protocols which enables these interactions. It is for this reason that the adoption of open standards by software providers is important to ensure interoperability. ### UX Functions of an Identity Wallet An identity wallet must provide the user with a UI that will enable them to: 1. Bind the identity of the Holder to the wallet 2. Request and receive credentials 3. Present (and possibly selectively disclose) credentials for verification 4. Manage credentials including auditing capabilities & consent management 5. Manage keys related to DIDs 6. Manage user settings 7. Provide help functionality ## Operating Model of Wallets There are three different ways a wallet can be operated, and any of them may be fully decentralised, centralised, or managed: * **Non-custodial**: all the associated keys are under the control of the Holder (most likely decentralised). * **Custodial**: all the associated keys are under the control of the custodian (most likely centralised). * **Hybrid**: a combination of Holder and custodian controls (most likely managed). Non-custodial wallets operate as per the Holder’s discretion and cannot be accessed by third parties unless the Holder provides consent. Generally, a non-custodial wallet is not linked to any external data storage, therefore, if the Holder loses their device or is locked out of their wallet application, they are unable to retrieve the contents of the wallet. Custodial wallets enable third parties to manage a Holder’s data on their behalf. Generally, third parties acting on a wallet Holder’s behalf work as intermediaries between the Holder and other wallets / services. A hybrid wallet can support Privacy- & Security-by-Design by enabling the Holder to maximise their privacy and exercise their data rights. However, as it is partly custodial, it can provide an option to help the Holder if they lose their wallet or obtain a new device. This may include key escrow services, together with wallet backup capabilities. ## The Meeco Wallet Find out more about Meeco’s Wallet by viewing our [Wallet product page](https://www.meeco.me/wallet). # Ecosystems Meeco's Secure Value Exchange (SVX) platform supplies the building blocks to implement an interoperable data ecosystem, designed around your enterprise use cases. In Web3, those use cases unlock the power of permissioned personal data and lay the foundation to create Personal Identity Ecosystems ([PIE’s](#types-of-ecosystems)). This new paradigm vastly increases user experience, privacy and security for your organisation and its end-users. Enterprises can explore radically new business opportunities built on digital trust, or, upgrade existing successful Web2 apps to Web3 by embracing trends such as: * [decentralised identity](/svx-v3/concepts/digital-identity) * [verifiable credentials](/svx-v3/concepts/verifiable-credentials) * [privacy-by-design](/svx-v3/concepts/privacy-and-security-by-design), and * [security-by-design](/svx-v3/concepts/privacy-and-security-by-design) ## Types of Ecosystems Depending on the desired reach of a use case, an enterprise can choose to implement different types of ecosystems: * **Open Ecosystems (aka Public Ecosystems)**: for broadly applicable use cases, such as the issuance, verification and management of a driver’s license, university diploma or first aid certificate across various organisations and users. * **Closed Ecosystems**: * **Private Enterprise Ecosystems**: [Verifiable Credentials (VCs)](/svx-v3/concepts/verifiable-credentials) issued by an enterprise to its users. For example: a company issues an access VC to employees, enabling them to gain access to software or buildings via a verification workflow. * **Personal Identity Ecosystems (PIE’s)**: are user-centric networks and platforms specifically designed around digital identities and personal reputation management while offering high standards for end-user privacy and data protection. * **Linked or Interoperable Ecosystems**: combine a government credential with a means of payment to allow frictionless onboarding to an eCommerce platform or service. **PIEs** enable data oriented relationships between consumers and service providers. Knowing that these ecosystems will thrive on user adoption and data availability, use cases should focus on trust and reliability of its ecosystem. Once an ecosystem has proven its value through various use cases and has yielded a vast user base, further growth will depend on ecosystem [interoperability](#interoperability) as it will attract and share participants of neighbouring ecosystems. *Source: Liminal Research: “The Life of PIEs, The Journey to Personal Identity Ecosystems” (2021)* ## Participants and Components of an Ecosystem [SVX](/svx-v3/platform/platform) delivers modular components to build an enterprise ecosystem. There are different ecosystem participants that act within various roles. Meeco has developed and defined participants and their roles within SVX as follows: * **Identity Providers (IDP)** together with trust anchors bootstrap the ecosystem by delivering verifiable data and promoting trusted relationships. * **Digital identity wallets** allow users to hold and manage their digital identity, assets, credentials, cryptographic keys and DID’s. * **Secure data stores** enable enterprises to securely store their own and their customer’s data. They also allow wallet Holders to back up data from their identity wallet and securely store or share private data. * **Verifiable Data Registries (VDR)** allow Issuers and Verifiers to publish relevant information for stakeholders to view, including credential revocation transactions, credential schemas, and list other trusted Issuers and Verifiers. ## Interoperability As the number of data ecosystems grow, it will become more beneficial for the participants involved to combine or join ecosystem networks. This will allow them to share services and yield mutual benefits. Whether it is sharing a credential to a trusted Verifier from another ecosystem, or issuing credentials to end-users that have onboarded via an external ecosystem, linked ecosystems will enable wider reach for enterprises and provide end-users with seamless experiences. # Information Security Meeco’s Information Security Management System (ISMS) is a framework of policies and controls that systematically manage security and risks across Meeco’s operations and technology. Meeco follows the [ISO27001](https://www.iso.org/standard/27001) standard to manage Information Security. ISO27001 is a set of specifications detailing how to create, manage, and implement ISMS policies and procedures. Meeco’s ISMS is designed to establish holistic information security management capabilities and to embed them in our day-to-day activities. This includes our goal to digitise non-digital assets and services, such as Verifiable Credentials (VCs) and to never store unencrypted customer data. Our digital ambitions related to SSI and Web3, require us to continuously implement and improve our security policies and controls. An artefact of these continuous efforts is a yearly ISO27001 audit and [accreditation](https://www.meeco.me/security#:~:text=ISO%2027001%3A2022%20audited%20and%20certified). ## Meeco’s ISMS Security Controls ISMS Security Controls span multiple domains of Information Security as specified in the ISO27001 standards. | **Control** | **Description** | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ***Information Security Policies*** | Overall direction and support to help establish appropriate security policies. | | ***Asset Management*** | This component covers Meeco’s assets such as software codebase, intellectual property and data within and beyond the corporate IT network which may involve the exchange of sensitive business information. | | ***Communications and Operations Management*** | Daily IT operations such as service provisioning and problem management follow IT security policies and ISMS controls. | | ***Access Control*** | This policy mainly deals with limiting access to authorised personnel and monitoring network traffic for abnormal behaviour. Access permissions relate to both digital and physical mediums of technology. The roles and responsibilities of individuals are well defined, with access to business information available only when necessary. | | ***Information Security and Incident Management*** | Meeco identifies and resolves IT issues in ways that minimise the impact to end-users. | | ***Business Continuity Management*** | Meeco avoids interruptions to business processes whenever possible. Ideally, any disaster situation is followed by recovery procedures to minimise the damage. | | ***Compliance*** | Meeco’s security requirements are enforced as per regulatory bodies, including ISO27001 and GDPR. | | ***Cryptography*** | Meeco has developed its [CKMS (Cryptography Key Management System)](/svx-v3/platform/keys) which includes a high-level set of rules that were established by Meeco. These rules describe the goals, responsibilities, and overall requirements for the management of cryptographic key-related material used to protect Meeco and its customer’s data and critical information. | | ***Supplier Relationships*** | Our third party vendors and business partners may require access to our network and sensitive customer data. Meeco has adopted controls to mitigate potential risks through IT Security Policies and contractual obligations. | ## Meeco’s Privacy Policy. For a comprehensive description of our Privacy Policy, please view the policy [here.](https://www.meeco.me/privacy-policy) ## Vault-specific data security All personal data at rest is encrypted with symmetric key encryption based upon AES-256-GCM. Additionally, all data is encrypted on a per user basis. If data is exchanged Vault-to-Vault a unique and encrypted shared space is generated. For each encryption space, each user has different symmetric keys. Symmetric keys are stored into a [Keystore](/svx-v3/platform/keys) and are encrypted with asymmetric key encryption based upon RSA-4096. The private key for this is derived from a passphrase created by the user and entered during [Vault](/svx-v3/platform/vault) creation. In addition to the encryption, the Vault and Keystore are secured through the user’s unique personal log-in and/or device PIN Code. Meeco support Anti-Correlation of Customer Information by ensuring that every connection between two Vaults has a distinct identity which can prevent correlation even if two Issuer Vaults were to collaborate. SVX ensures that every interaction with a VC (issuance, verification, revocation) can't be related by maintaining pairwise pseudonymity. For example, when Vaults share VC data between connections, we use connection IDs; resulting in Issuers and Verifiers knowing each user by a different ID. Additionally, every attribute has a universally unique identifier (UUID). For full transparency, Meeco makes this important documentation publicly available and has published additional information about the key encryption library, which is open sourced and available on GitHub at [Meeco](https://github.com/Meeco) for review and auditing. This is further supported by documentation at [docs.meeco.me](https://docs.meeco.me/). ## Additional Security Methods​ The following operational security measures further enhance our data security: #### 1. Security Awareness and Employee Education All Meeco employees undertake and maintain Security Awareness Training. #### 2. Encryption To protect our data, Meeco use data encryption at rest, in transit, and in cloud​. We use two types of cryptographic primitives:, which are generated on the device controlled by the end-user. * **Data Encryption Keys (DEKs)** which: ​ * Are symmetric encryption keys used to encrypt data. * Use the cryptographic algorithm: AES-256-GCM​. * **Public-key cryptography** (asymmetric encryption​) which: * Allow users to securely share DEKs (sender encrypts with recipient’s public key)​. * Identify users in the Vault (used for login)​. * Use the encryption cipher: RSA-4096​. #### 3. Microsoft Azure Security Tools Our data security is managed in Azure via: * **Encryption**: Azure Disk Encryption, Azure storage service encryption, transparent data encryption. * **Rights Management**: Azure Right Management is a cloud-based service that uses encryption, identity, and authorisation policies to secure files. * **Access Control**: Azure role-based access control to restrict access to Azure resources based on user roles. * **Network**: To protect data in transit, we use SSL/TLS when exchanging data across different locations. * **Monitoring**: Microsoft Defender for Cloud automatically collects, analyses, and integrates log data from Azure resources, the network, and connected partner solutions, such as firewall solutions, to detect real threats and reduce false positives. Log Analytics provides centralised access to logs and helps in the analysis of data to create custom alerts. # Personal Data & Attributes The General Data Protection Regulation (GDPR) defines personal data as “any information which (is) related to an identified or identifiable natural person.” There is an extensive list of personal data types that are considered to aid in the identification of people and things. Examples include: * Given name * Family name * Telephone number * Social security number * Address * Financial account data * Information related to appearance * Biometrics ## Personally Identifiable Information The list above shows clear examples of Personally Identifiable Information (PII). PII refers to information that can be used to identify a specific individual and is considered highly sensitive information. The protection of PII is more than a legal duty: it is a crucial aspect of data privacy. While the concept of PII is obvious to most people, there are forms of data that are more abstract which can still be used to link back to a subject. For example, answers provided in a survey and the date and time the survey was taken can be used to correlate the identity of the survey participant. Correlation is the concept that refers to combining pieces of personal data to provide insights into a person's behaviour, characteristics or even identify the physical person. It is important to note that the category of data known as *sensitive personal data* is subject to a higher level of protection. Sensitive personal data include anything related to genetic and health data, and political, religious or ideological beliefs. ## Types of Data Meeco identifies and categorises the different data types involved in various interactions. We ensure that each workflow follows best practices tailored to the specific data types it utilises. The data types Meeco engages with include: * **Raw data**: Data that usually only has meaning to the person/service that provided it, or a group of people or services. Most data falls in this category. * **Verifiable data**: A digital representation of data that is either typically found in physical documents or something that cannot be represented by it. The entity signing the data is considered reliable by the entity relying on the data. The information is digitally signed and therefore is tamper resistant and instantaneously verifiable. It makes sense to describe these using a semantic data model (see point below). * **Self-attested data** A sub-category of verifiable data that has the same properties, however the person that is signing the data is the same as the person providing the data. * **Semantic data**: The data is organised in such a way that it can be interpreted meaningfully without human intervention. ## How Meeco Handles Data We design and develop our products with privacy- and security-by-design principles at their core. As per these frameworks we use end-to-end data encryption methods when storing and exchanging data. When using our products, enterprises and their customers can be assured that we never: * Sell data * Read or mine data in any way * Track data in any way * Build AI/ML models We ensure that your customers are always in control of their personal data, including their digital identity and assets. We provide tools for people to make informed decisions when sharing and receiving data, and help enterprises reduce cost and meet data compliance requirements on a range of use cases. # Privacy- and Security-by-design ### Privacy-by-design Privacy-by-design (PbD) is a framework that was developed in the 1990s by Dr Ann Cavoukian and has since been adopted by the Global Privacy Assembly. PbD’s purpose is to protect data, the data owners, data custodians, and those who exchange data in digital environments. It is built on seven principles: 1. Proactive not reactive, preventative not remedial 2. Privacy as a default setting 3. Privacy embedded into design 4. Full functionality: positive-sum not zero-sum 5. End-to-end security – full lifecycle protection 6. Visibility and transparency – keep it open 7. Respect for user privacy – keep it user centric PbD is not just about implementing these principles when designing and developing technology solutions, these principles should inform a company’s decision-making and business processes. By considering privacy at all stages of business development as well as privacy awareness with all staff, a company can strive to develop solutions that prevent privacy-related issues. ### Meeco’s PbD Implementation Meeco's Secure Value Exchange (SVX) platform is built with PbD in mind, we never read, mine or sell personal data. We provide the infrastructure for our partners to enable their customers to access, control and exchange their identity and personal data. We maintain user privacy by ensuring that all user data is end-to-end encrypted. This means that there is no way for anyone other than the data owner to view, edit, or manage the data without explicit consent of the owner. The SVX Portal and Wallet application both demonstrate user-centric design. This is visible via their user interfaces (UIs) at each stage of a workflow where information is clearly conveyed to the user. By plainly stating why and where action is required, including consent methods, users can make informed decisions when sharing their data. We hope that these PbD principles will be adopted by all of our customers when integrating with, implementing and utilising our APIs and supporting components. ### Security-by-design Security-by-design (SbD) is a concept that promotes the inclusion of security considerations at each stage of a product’s lifecycle. For example, instead of a product development team creating fixes or patches once a security threat has been identified, the entire team considers who, why and how a threat may occur at each stage of planning, design and development. By adopting this approach the final product delivered is more robust, less susceptible to data breaches, and generally more secure for users to engage with. ### Meeco’s SbD Implementation In August 2021, Meeco successfully passed the ISO27001 Security Audit and is now certified in Australia, Belgium and the UK. Meeco has successfully passed several major European and Australian retail bank security audits, along with an independent audit against the NIST Cybersecurity Framework by KPMG. We were able to achieve these outcomes by proving that SbD is implemented throughout our product lifecycle. Examples of how we achieve SbD are listed below: **Secure Software Development Life Cycle** * Security awareness and training * Static code analysis **Cybersecurity Mitigation Strategies** * Information Security Manual (ISM) and Essential Eight * ISO 27001 Controls / Security Council * Azure Security Center / Defender for Cloud **Separation of Concerns** * Separate development and operational teams # Secure Data Storage Both users and enterprises store a significant amount of data online, including personally identifiable information (PII), sensitive corporate data and customer information. More often than not, this data is not appropriately protected. A secure data storage solution is designed to protect the data from unauthorised access or use, while ensuring that data is available when needed. Here are some features that a secure data storage should have: * **Encryption**: Data is encrypted both in transit and at rest to ensure that even if it is intercepted or stolen, it cannot be read or used by unauthorised parties. * **Access Control**: Access to data is restricted to authorised parties. * **Logging and Auditing**: The storage solution maintains a log of all events related to the data, and provides audit logs to authorised users. * **Compliance with Standards and Regulation**: The storage solution complies with relevant data protection regulations, such as the General Data Protection Regulation (GDPR). It also follows best practices for security and data protection, such as those outlines by the National Institute of Standards and Technology (NIST). * **Data Integrity**: When exchanging data with other parties, it is essential to conserve integrity to ensure that the data remains accurate and unchanged throughout the transmission process. ## Meeco’s Secure Storage Solution Meeco has developed the Vault as part of our Secure Value Exchange (SVX) platform, a flexible secure data storage option that provides end-to-end encryption on all data types. It also includes encrypted peer-to peer-sharing with granular control over Shares. Via the use of the Vault APIs, our secure data technology can be embedded in new and existing applications such as digital wallets, mobile apps, web portals or back-up services. By default, users and organisations are authenticated via an OIDC provider. For details, see our [Vault](/svx-v3/platform/vault) information page. # Selective Disclosure / ZKP Selective disclosure (SD) is a concept strongly linked to self-sovereign identity (SSI). SSI was established to bring awareness to digital users who lack control of their digital identity online. It is a model that provides individuals with the tools and information required to manage their identity data themselves, without necessarily relying on a third party. If we consider that SSI promotes users sharing their data with whomever they want, for however long, then users should also be able to choose how much or how little information they share. The ability to manage the amount of data being shared takes form as SD. An additional layer to SD is zero-knowledge proof (ZKP) cryptography which enables Verifiers to request proof of information rather than specific details. For example, a Verifier may want to know if a Holder is over the age of 18, rather than asking for the Holder’s birthday (which is personally identifiable information), they can ask for proof that the Holder is over the age of 18 without the user having to disclose their date of birth. ## Meeco’s ZKP Roadmap Meeco is currently in the process of developing SD & ZKP capabilities via following pathways: ### Pathway 01 Allow users to store data as a set of attributes that allows them to have fine grained control over which attributes they disclose to a third party. ### Pathway 02 Use BBS+ Signatures that allow selective disclosure and holder blinding. The BBS+ Signatures is a multi-message digital signature; this allows us to share a piece of the Verifiable Credential (VC) and still prove its authenticity. This requires the Issuer to use BBS+ capable signatures when signing credentials (e.g. BbsBlsSignatureProof). ### Pathway 03 (Research) Use more advanced ZKP techniques known as predicates, that allow us to derive statements that can be useful for age verification. This option is based upon the usage of SNARK Circuits. The Issuer builds a fixed-size Merkle tree, whose leaves represent the attributes of the VC. Each leaf of the Merkle tree is the hash of the attributes key and value (e.g. `{ “name”: “Alice” } -> Hash(“name” | “Alice”)`). The tree is built deterministically, so that, starting from the same document, everyone can build the same tree. This allows us to use these attributes either as public inputs for the derived predicates or selectively disclose attributes. An interim step, if this capability was required urgently, is to issue a specific additional credential(s) as part of an issuance flow. For example, a Birth Certificate could also have a standalone "over 18", "over 15", "over 21" credential issued at the time of original issuance. This would have to be re-issued when the status changed (i.e. on the Holder's 18th birthday where they would have to re-request the supplementary credentials). # Tokens and Tokenisation This page explores the concept of tokens and tokenisation, including examples of how they are implemented. ## Tokens Tokens are digital representations of data or information. They enable their owner(s) to access, participate in, or take part in the development of a digital data ecosystem. Tokens can be owned and transacted, some hold monetary value and others are associated with access and processes. There are different types of digital tokens including: * **Authorisation tokens**: Used to verify the identity of users or systems and to grant or deny access to resources. An example is an OAuth token. * **Identity tokens**: Used to represent a user's identity and may contain personal information such as name, email address, and address. An example is an OpenID Connect token. * **Utility tokens**: Allow owners access (via encrypted key) to a particular network or blockchain. Owners can perform actions on the network, including assisting in its development, and can benefit from the network’s output. * **Security tokens**: Represent ownership of an asset and are fungible. * **Governance tokens**: Provide the owner with the rights to govern a decentralised organisation. * **Value tokens**: Hold value in the form of a digital object, for example art or music. They take the form of non-fungible tokens (NFTs). ## Tokenisation Tokenisation is the process of converting (sensitive) data into tokens. This tokenisation of data allows users, organisations, and assets to protect sensitive data while preserving its business utility. Data tokenisation provides higher levels of data security than encryption alone. When data is tokenised, all original sensitive personal, payment or identifiable data is removed. The sensitive data is kept in secure storage and only shared when really necessary. This method of data security is founded on “Zero Trust” principles whereby no user or device is trusted to access the stored data until their identity and authorisation are verified. > “Tokenization simultaneously preserves the utility of sensitive data while allowing it to remain secure and compliant with most regulations. Tokenization allows sensitive data to remain secure in transit, in use, and at rest, enabling a flexible range of data use cases that would otherwise be unsafe or inadvisable.” Buchfiel, A. (2022, March 31). What is data utility and how can tokenisation preserve it? Tokenex. ## Implementations The benefits of tokenising data is becoming more widely known, largely in part due to new regulations and standards. For example, in the United States, the Health Insurance Portability and Accountability Act (HIPAA), and in Europe, the General Data Protection Regulation (GDPR) require special handling, anonymisation and secure storage of personally identifiable information (PII). Due to these data governance requirements, companies from a variety of disciplines are utilising the tokenisation of business, employee and customer data as a means to store and exchange PII. Common implementations of data tokenisation include: * Payment services * User authentication * Asset management * Exercising user rights in an ecosystem or platform # Verifiable Credentials Digital credentials are becoming more commonly used to assert and transfer information about people, entities and things. A credential is a structred document that contains key-value pairs (referred to as claims). The W3C Verifiable Credentials (VCs) Data Model is a specification that enables people, entities and things to share credentials with third-parties to prove they possess certain attributes, knowledge and permissions in a machine-verifiable way. VCs are compiled of a set of claims made about a Holder / Subject. They can be imagined as digital equivalents of physical documents (e.g. driver licences, passports, birth certificates). What differentiates them from physical documents and other non-secure forms of digital data is that they are tamper-resistant and can be cryptographically verified. In addition to this, VCs: * Are based on international standards such as those published by the [W3C](https://www.w3.org/TR/vc-data-model/) * Include decentralised identifiers [DIDs](/svx-v3/platform/did) (for all actors) * Are designed to be globally interoperable * Require cryptographic proof throughout the credential lifecycle * Can be used across ecosystems * Adhere to a common schema * Utilise common / shared lists for resolving and revocation ## The VC Ecosystem ### Issuer, Holder and Verifier Inside the VC Ecosystem are three distinct roles: an *Issuer*, a *Verifier*, and a *Holder*. At the centre of the ecosystem is the Holder (not to be confused with the subject although these are often the same). The exchange of VCs starts with the Issuer who generates the credential and issues it to the Holder. The VC contains: * A set of claims about the Holder (e.g. name, date of birth) * The Issuer’s signature * Credential metadata (e.g. expiry date) * The credential identifier (a unique number) Once issued, Holders can store their VCs in a digital wallet. In the event a Holder needs to provide evidence of, for example, their identity, a skill, or access rights, they can share proof of one or more claims stored within their VC(s). They share this proof with actors inside the ecosystem called Verifiers via a Verifiable Presentation. A Verifiable Presentation is the requested information (VCs) packaged by the Holder and presented to a Verifier. These presentations are verified by the receiving party in order to perform a service. ### Verifiable Data Registry A verifiable data registry (VDR) is a role undertaken by a system within a VC Ecosystem. The purpose of this role is to mediate the actions undertaken by the actors in the ecosystem. These actions include the creation and verification of identifiers, keys, VC schemas etc. VDRs take many forms, the type of ecosystem being orchestrated will determine which VDR should be used. When sharing and exchanging VCs, the W3C trust model only requires that “all entities trust the verifiable data registry to be tamper-evident and to be a correct record of which data is controlled by which entities.” The different types of VDRs include: * **Trusted databases**: A database governed by one or more organisations that is managed centrally, across multiple systems or on a cloud. * **Ledgers**: A verifiable transaction log where entries are only ever added, not removed from the ledger. * **Centralised ledgers**: Managed by a ledger operator and do not require a consensus mechanism. * **Distributed ledgers**: A ledger that is replicated across many systems or entities, where transactions are updated in unison. Requires a consensus mechanism. * **Blockchains**: Use cryptographically linked blocks of data that build as more transactions occur. Meeco’s products are VDR agnostic, any of the above VDR types can be used when creating and managing a VC Ecosystem with Meeco's Secure Value Exchange (SVX) platform. ### Digital Wallets Digital wallets enable users to manage their digital assets easily and securely from the device(s) of their choosing. Wallets are commonly used for the management of data and transactions, ranging from identity documentation (driver licences and certificates), financial (payments and transfers), tokens (fungible and non-fungible), and loyalty programs (vouchers and point accumulation). To better understand how VCs are managed in digital wallets, see our [Digital wallets](/svx-v3/concepts/digital-wallets) information page. ## VCs in real-world applications To see how Verifiable Credentials can be used in different workflows, please view Meeco’s case studies and existing [customer applications](https://www.meeco.me/powered-by-meeco) to find out more. # Terminology ## Claim Attribute represented as a name-value pair. ## Classification A link between a [Classification Node](#classification-node) and a classified entity. [Items](#item), [Slots](#slot) and [Templates](#item-template) can have Classifications. ## Classification Node A [Classification Scheme](#classification-scheme) consists of a tree of ***Classification Nodes***. A Classification Node: * belongs to a Classification Scheme * has a parent Classification Node, unless it is the root node * has property `name` * has property `label` * has property `description` * has property `image` ## Classification Scheme Combinations of [Classifications](#classification) are called ***Classification Schemes***. ## Connection A persistent channel via which two entities can share information (e.g. [Items](#item), DIDs). ## Credential For a comprehensive understanding of "Credential(s)", please refer to the [Verifiable Credentials](/svx-v3/concepts/verifiable-credentials) section. ## Credential Schema A document that is used to guarantee the structure, and by extension the semantics, of the set of **claims** comprising a **Verifiable Credential**. A shared Credential Schema allows all parties to reference data in a known way. See [reference here](https://www.w3.org/TR/vc-data-model/#dfn-credential). ## Credential Template The defining properties of the resulting **Credential**. Credential Templates generally include: * template name * associated credential schema * Issuer URL * Issuer logo * styling information (background and text colour) ## Data Encryption Key (DEK) Are `AES256-GCM` keys used to encrypted and decrypt user data. They are stored in the [Keystore](#keystore) encrypted with the **Key Encryption Key**. It is possible for a user to have multiple Data Encryption Keys. ## Decentralized Identifier (DID) [URIs](https://w3c.github.io/did-core/#dfn-uri) that associate a [DID subject](https://w3c.github.io/did-core/#dfn-did-subjects) with a [DID document](https://w3c.github.io/did-core/#dfn-did-documents) allowing trustable interactions associated with that subject. [DIDs](https://w3c.github.io/did-core/#dfn-decentralized-identifiers) have been designed so that they may be decoupled from centralized registries, identity providers, and certificate authorities. Specifically, the controller of a [DID](https://w3c.github.io/did-core/#dfn-decentralized-identifiers) can prove control over it without requiring permission from any other party. ## Derivation Artefact Required in the process of generating or re-generating a **Passphrase Derived Key**. Derivation Artefacts include: * Number of iterations * Salt * Derived key ## DID Subject The entity identified by a DID and described by a DID Document. DID subjects include: * people * organizations * physical entities * digital entities ## Distributed Ledger Technology (DLT) An umbrella term for technologies that provide distributed, append-only storage mechanics based on a consensus algorithm. Blockchain and hashgraph technologies are included under the term DLTs. ## Distributed Public Key Infrastructure (DPKI) Same as PKI, but does not require a centralized authority to provide authenticity. ## Ecosystem A group of organizations, users, and things that interact within a particular environment to achieve a (common) goal. ## End-to-end Encryption (E2E) A system of communication where only the users communicating can read the messages. It prevents data from being read or secretly modified, other than by the true sender and recipient(s). The messages are encrypted by the sender (via the use of encryption keys), they are stored, encrypted, by the recipient, and are decrypted (read) by the recipient with another set of keys. ## End-users A role within **SVX**. End-users, including **Wallet Holders**, partake in the exchange and sharing of data with **Issuers** and **Verifiers**. Via the use of Meeco’s Wallet application, they are able to, but not limited to: * Register with **Tenants** * **Connect** with **Organizations** * Import credentials * Import and respond to **Presentation Requests** ## Ephemeral DID DID which is self-contained or generative, does not need to be represented in VDR. ## Issuer A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. See reference here. ## Item A group of [Slots](#slot) related by a topic. Common examples of Items: * user profile * club membership * flight reservation The Slots in an Item are keyed by their name property and contain only encrypted values. Detailed documentation can be [found here](/svx-v3/guides/api-guides/vault/items-and-slots). ## Item Template A predefined list of empty [Slots](#slot). Each Item is created by cloning a template and filling in the Slots with data. Detailed documentation can be [found here](/svx-v3/guides/api-guides/vault/items-and-slots). ## JSON File Type JSON is an open standard file format and data interchange format that uses human-readable text to store and transmit data objects consisting of attribute-value pairs and arrays. It is a common data format with diverse uses in electronic data interchange, including that of web applications with servers. ## JSON Web Tokens JSON Web Token is a proposed Internet standard for creating data with optional signature and/or optional encryption whose payload holds JSON that asserts some number of claims. The tokens are signed either using a private secret or a public/private key. ## Key Encryption Key (KEK) Used to encrypt all other keys (**Data Encryption Keys** and **Keypairs**) before they are stored in the [Keystore](#keystore). The Key Encryption Key is encrypted with the [Passphrase Derived Key](#passphrase-derived-key-pdk). ## Key Exchange A process where at least two parties exchange cryptographic key(s) with the intention to use it/them for encryption or authentication. ## Keypair A pair of private key(s) and public key(s) that are mathematically linked to each other. Public keys are used to encrypt data, and the private key of the keypair is used to decrypt that data. This is known as asymmetric encryption. ## Keystore A component within SVX. The Keystore enables users to store and manage their cryptographic keys. This is where the [Data Encryption Keys](#data-encryption-key-dek), [Public/Private Keypairs](#keypair), and the [Key Encryption Key](#key-encryption-key) are stored along with the [Derivation Artefact](#derivation-artefact). All of the stored keys are encrypted with the **KEK**, except for the **KEK** itself, which is encrypted with the **Passphrase Derived Key**. No encryption is done in the Keystore; the **Cryppo library** aids in creating and using keys. Additional information can be [found here](/svx-v3/tools/cryppo). ## Organisation An entity within **SVX**. An Organisation belongs to a Tenant and is managed by one or more **Organisation Administrators**. ## Organisation Administrator A role within **SVX**. Organisation Administrators are individuals (users) who have administrator access and permissions to operate an **Organisation**. An Organisation Administrator is responsible for the actions that take place within their Organisation, including: * Issuing credentials * Verifying credentials * Revoking credentials * Creating and managing **Connections** ## Passphrase A string of words that are used to authenticate a user when accessing a digital service or system. Passphrases are considered more secure than passwords as they are harder to decipher. ## Passphrase Derived Key (PDK) A `PBKDF2` key. To generate or re-generate this key, a passphrase and derivation artefacts are required. Derivation artefacts include: * Number of iterations * Salt * Derived key length In the current iteration of our `Secret Key` authentication and passphrase derivation, the number of keys `Number of iterations` and `Derived key length` are static, and the Salt is pulled from the Secret Key. ## Personally Identifiable Information (PII) Identifiers/attributes that may serve to uniquely identify a subject of the information. ## Presentation Data derived from one or more [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials), issued by one or more [Issuers](https://www.w3.org/TR/vc-data-model/#dfn-issuers), that is shared with a specific [verifier](https://www.w3.org/TR/vc-data-model/#dfn-verifier). See reference [here](https://www.w3.org/TR/vc-data-model/#dfn-credential). ## Presentation Definition Presentation Definitions are objects that articulate what proofs a Verifier requires. These help the Verifier to decide how or whether to interact with a [Holder](https://identity.foundation/presentation-exchange/spec/v2.0.0/#term:holder). Presentation Definitions are composed of inputs, which describe the forms and details of the proofs they require, and optional sets of selection rules, to allow Holders flexibility in cases where many different types of proofs may satisfy an input requirement. See reference [here](https://identity.foundation/presentation-exchange/spec/v2.0.0/#term:presentation-definition). ## Presentation Request (PR) Presentation Requests are transport mechanisms for [Presentation](https://identity.foundation/presentation-exchange/spec/v2.0.0/#term:presentation). Presentation Requests can take multiple shapes, using a variety of protocols and signature schemes not refined in this specification. They are sent by a [Verifier](https://identity.foundation/presentation-exchange/spec/v2.0.0/#term:verifier) to a [Holder](https://identity.foundation/presentation-exchange/spec/v2.0.0/#term:holder). Defining Presentation Requests is outside the scope of this specification. See reference [here](https://identity.foundation/presentation-exchange/spec/v2.0.0/#term:presentation-definition). ## Private Key (PrK) A secret key in asymmetric cryptography used for decrypting ciphertext to plaintext. ## Public Key Infrastructure (PKI) Infrastructure distributing cryptographic **public keys** based on a chain-of-trust, which is built around centralized authorities (entities issuing **Root Certificates**). ## Public Key (PuK) A public key linked directly to a specific entity, used to encrypt plaintext into ciphertext, which can only be decrypted with the corresponding **Private Key**. ## Relying Party (RP) An entity that relies upon the subscriber's **credentials**, typically to process a transaction or grant access to information or a system. ## Root Certificates In cryptography and computer security, a root certificate is a public key certificate that identifies a root certificate authority (CA). Root certificates are self-signed and form the basis of an X.509-based public key infrastructure (PKI). See reference [here](https://en.wikipedia.org/wiki/Root_certificate). ## Secret Key (also see **Private Key**) In symmetric cryptography, a secret key (or "private key") is a piece of information or a framework used to decrypt and encrypt messages. Each party taking part in a transaction that is intended to be private possesses a common secret key. See reference [here](https://www.hypr.com/security-encyclopedia/secret-key). The secret key is a component of the authentication flow. The format for version 1 is as follows: `{version}-{username}-{salt}`. The `username` is generated by the server, and the `salt` is a 256-bit randomly generated key, which is base58 encoded and has a hyphen (-) at each 6th character. The salt component is created on the client and stored securely by the user. It is used to generate: 1. An encryption key [(aka Passphrase Derived Key (PDK))](#passphrase-derived-key-pdk) with which to encrypt your [Key Encryption Key (KEK)](#key-encryption-key-kek). 2. A password that, along with a username, will be used for [Secure Remote Password (SRP)](#secure-remote-password-srp) authentication. ## Secure Remote Password (SRP) An authentication method that sends proof that a user knows their password without revealing the actual password to the server. Additional information can be found [here](https://en.wikipedia.org/wiki/Secure_Remote_Password_protocol). ## Security Rights (SRs) The permissions an individual user or a computer application holds to read, write, modify, delete, or otherwise access a computer file; change configurations or settings, or add or remove applications. See reference [here](https://soffront.com/glossary/access-rights/). Within **SVX**, one can differentiate between two types of security rights: * External security rights, which are understood by other components in SVX. * Internal security rights, which [ATOM](https://www.meeco.me/platform#component-atom) uses to manage itself. ## Security Rights Token (SRT) A token that contains security rights assigned to a user or agent, which can be used as proof that it can perform certain actions. ## Share A Share is created when a user grants access to one of their [Items](#item) to another user that they have [Connected](#connection) with. The **Item** is re-encrypted with a [Data Encryption Key](#data-encryption-key-dek) and shared with the recipient of the Share. An Item you have received via a Share can be shared with another user, but you cannot alter any of its **Slots**. Only the original creator of the Item can update the Share, other than deleting it. Detailed documentation can be found [here](/svx-v3/guides/api-guides/vault/connections-and-sharing). ## Slot A Slot is the smallest data entity in the [Vault](#vault). An Item is made up of Slots, which are defined by the `name` property. Each Slot has a `name`, a `label`, and a `value`. Slots are able to be shared after two users have made a [Connection](#connection) with each other. Note that the API does not return the `value` property but `encrypted_value`. The API will not allow storing any unencrypted data in either `value` or `encrypted_value`. Slot values are always stored in an encrypted form, and only the user can decrypt and read them. Once encrypted and serialized, a Slot value of "BMW" would look something like this: `"encrypted_value": "Aes256Gcm.2hDl.LS0tCml2OiAhYmluYXJ5IHwtCiAgQWQwSThDZk5qRnFycmFuMAphdDogIWJpbmFyeSB8LQogIDJXVklzbUxOSWVoOHZIVDB1ZzBtZVE9PQphZDogbm9uQQo="`. Slots are typed, but the values cannot be checked to match the given type, as the API does not have decrypted keys for these items. Example Slot types are: * `key_value` * `bool` * `date` * `datetime` * `image` * `url` * `phone_number` * `email` * `password` * `attachment` Notice that new types cannot be created; `key_value` should be the default type used. ## Software Development Kit (SDK) A collection of software development tools in one installable package. They facilitate the creation of applications by having a compiler, debugger, and sometimes a software framework. ## Signing Key See **Private Key**. ## Subject A principal of a **Credential**. It can be a person, organization, thing, or entity. ## Secure Value Exchange (SVX) Meeco's proprietary platform. [SVX](https://www.meeco.me/platform) provides customers with the building blocks to deliver trusted networks. ## (Verification) Submission A term used within SVX but is identical to **Verifiable Presentation**. ## Tenant An entity within [SVX](https://www.meeco.me/platform). A Tenant is operated by **Tenant Administrators** and is responsible for the governance of its **Tenancy** participants (including **Organisations** and **End-users**). ## Tenant Administrator A role within [SVX](https://www.meeco.me/platform). Tenant Administrators are individuals (users) who have administrator access and permissions to operate a **Tenant**. A Tenant Administrator is responsible for the actions that take place within their Tenancy, including: * Onboarding, managing and governing Organisations. * Registering and managing **End-users**. ## Tenancy(ies) A Tenancy is operated by an enterprise/company, referred to as a **Tenant** and consists of **Organisations**, and **End-users**. ## Uniform resource identifier (URI) A Uniform Resource Identifier is a unique sequence of characters that identifies a logical or physical resource used by web technologies. URIs may be used to identify anything, including real-world objects, such as people and places, concepts, or information resources such as web pages and books. ## Universally unique identifier (UUID) A number assigned to any type of data set or attribute to make it uniquely identifiable. ## Vault Meeco’s Vault is where users can store and **Share** the [Items](#item) they create with **Connections** they establish. A Vault user’s data is **end-to-end encrypted** and is only accessible by them. Additional information can be found [here](/svx-v3/concepts/terminology). ## Verifiable Credential A verifiable credential is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build [verifiable presentations](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-presentations), which can also be cryptographically verified. The [claims](https://www.w3.org/TR/vc-data-model/#dfn-claims) in a credential can be about different [subjects](https://www.w3.org/TR/vc-data-model/#dfn-subjects). See reference [here](https://www.w3.org/TR/vc-data-model/#dfn-credential). (and so on for the remaining terms) ## Verifiable Data Registry (VDR) In the context of decentralised identity, is a place where Decentralised Identifiers (DIDs) can be anchored to. ## Verifiable Presentation A tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. Certain types of verifiable presentations might contain data that is synthesized from, but do not contain, the original [verifiable credentials](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials) (for example, zero-knowledge proofs). See reference [here](https://www.w3.org/TR/vc-data-model/#dfn-credential). ## Verification Request See **Presentation Request**. ## Verification Template The defining properties of the resulting **Presentation Request**. Verification Templates generally include: * template name * purpose (reason for requesting the specified **Credential(s)**) * **Credential Schema(s)** Verification Templates can be used repeatedly to form the basis of many different **Presentation Requests**. ## Verifier A role an [entity](https://www.w3.org/TR/vc-data-model/#dfn-entities) performs by receiving one or more [Verifiable Credentials](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials), optionally inside a [Verifiable Presentation](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-presentations) for processing. Other specifications might refer to this concept as a relying party. See reference [here](https://www.w3.org/TR/vc-data-model/#dfn-credential). ## Verifying Key A well-known key link directly to a specific entity. Used to confirm signatures. Technically, it is a public asymmetric key. ## Wallet Software that enables the wallet’s controller (the end-user or **Wallet Holder**) to generate, store, manage and protect cryptographic keys and [Verifiable Credentials](#verifiable-credential). It allows the person to take actions (e.g. accept and present credentials) and setup peer-to-peer communication. ## Wallet Holder An entity that stores and “owns” [Verifiable Credentials](#verifiable-credential). A Wallet Holder’s **Credentials** are cryptographically signed with the Holder’s signing key in the ‘holder’ section of the [Verifiable Credential](#verifiable-credential). ## Zero Knowledge Proof(s) (ZKP) In cryptography, a zero-knowledge proof or zero-knowledge protocol is a method by which one party can prove to another party that a given statement is true while the prover avoids conveying any additional information apart from the fact that the statement is indeed true. ## Zero Value Knowledge (ZVK) A system that has no knowledge (by using end-to-end encryption) of the data value, whilst allowing metadata to be accessible to the service. Metadata might include a data label (such as "street\_name"), or classifications (such as "home"). # Secure Value Exchange Meeco’s Secure Value Exchange (SVX) platform is a series of components that enable enterprises to put their customers in control of their personal data, identity and digital assets. These components can be integrated into existing systems via our APIs, SDK, or standalone tools as a way for enterprise customers to deploy trusted personal data ecosystems. SVX at its core provides the following capabilities: secure data storage, verifiable credentials management, and digital asset management. Details of the platform’s components and architecture can be seen below. ## Components Components can be used individually, or combined to enable enterprises with extensive data and digital asset management solutions. Each component has been designed to address specific issues and concerns in different areas. These include: * Secure data storage and management (workplace, customer and asset data) * Verifiable credentials (issuing, revoking and verifying credentials) * Digital asset management (decentralised identifiers) * Cryptographic key management * Consent, permission and authorisation management Each component can be accessed via our extensive API, SDK, or via our low-code [Portal](/svx-v3/platform/portal) and digital Wallet application. SVX components include: * **Vault** – Secure data storage * **Keys** – Encryption key management * **Exchange** – Peer-to-peer encrypted connections & sharing * **Consent** – Consent & permission management * **Events** – Events, audits & notifications * **Wallet** – Self-Sovereign Identity (SSI) Wallet & services * **Credentials** – W3C Verifiable Credentials management * **ATOM** – Multi-tenancy & organisation management * **Devtools** – Developer tools & documentation ## Platform Deliverables SVX has been designed and developed with key values in mind: * Remove friction * Enable trust * Manage risk * Personalise experiences * Increase loyalty * Develop new business models These values have been formed after extensive research into the space, with a focus on the requirements of the businesses and organisations who engage in it. By developing flexible digital components that can be implemented in any discipline, domain or ecosystem, enterprises can: * Restore digital equity and trust between them and their customers * Reduce costs * Meet data compliance requirements When using SVX, these deliverables can be easily achieved as each component has been created with security, privacy, standards, and regulatory compliance in mind. We encourage you to review our documentation or speak to us today to discuss how we can help your company deliver more robust, secure and compliant infrastructure. ![](/files/4NKD0bUqxKnkZOf1M1gi) # Authorisation, Tenant & Organisation Manager (ATOM) Meeco's Authorisation, Tenant and Organisation Manager (ATOM) enables the creation of a hierarchy of organisations within the Secure Value Exchange (SVX) platform. These organisations have associated administrator users, which are defined as Tenant Administrators and Organisation Administrators. Dependent on the role, an Administrator will have a set of security rights which denote what actions they can undertake. ATOM manages not only Administrator security rights but also the security rights of the Tenants and Organisations as individual entities. In doing this, ATOM allows SVX components to authorise the actions of all parties within the ecosystem. This creates a robust, secure and accountable exchange of data between the different parties. ## Security Rights Security rights control permissions granted to Tenants, Organisations, and their Administrators. These rights determine what specific activities and operations each entity can perform, ensuring proper access control and data protection. For Tenants, security rights govern their overarching privileges, such as managing and provisioning Organisations, End-users, and managing credential schemas. Organisations, as subsets of Tenants, have security rights that pertain to data management within the tenant environment, including issuance and verification of verifiable credentials. Administrators, who oversee the Tenant and/or Organisation, are granted security rights that enable them to perform administrative tasks, manage user access, and configure system settings. By effectively managing security rights, the platform ensures that each entity has the appropriate level of access and control over the system's functionalities while maintaining the necessary security and privacy measures. ## Applications for M2M Communication In addition to user interactions, ATOM facilitates machine-to-machine (M2M) communication, enabling applications to call ATOM's APIs. Applications interact on behalf of an Organisation. By leveraging the platform's capabilities for machine-to-machine communication, Organisations can achieve greater efficiency, scalability, and interoperability in their application ecosystems. ## Event Logs ATOM is built as an event system, providing numerous benefits, including comprehensive auditing capabilities. The event-driven architecture of ATOM enables the capture and logging of various events that occur within the system. By logging events, ATOM allows for detailed auditing and tracking of actions, providing a valuable tool for compliance, security, and accountability purposes. # Credential Service Meeco’s Credential Service enables the issuance, request, presentation, verification and revocation of Verifiable Credentials (VCs) within the Secure Value Exchange (SVX) platform. It does this by leveraging open standards to facilitate the creation of trust-based, data exchange ecosystems. Once onboarded to SVX, Issuers and Verifiers can develop a range of credential services based on secure, cryptographic, tamper-proof data exchanges. Our Credential Service enables trusted Issuers to design and issue custom VCs which can in-turn be verified by trusted Verifiers. The Credential Service is integrated with the [Portal](/svx-v3/platform/portal) and Wallet offerings to support the complete credential life cycle. ## VCs and VPs The VC data model that we employ has been established as a standard by [W3C](https://www.w3.org/TR/vc-data-model/). Both VCs and Verifiable Presentations (VPs) are included in this standard and it is important that both concepts are understood when exploring VC workflows. VCs are comprised of one or more tamper-evident claims plus associated metadata, all of which relate to an entity (a natural or legal person, object, place or thing). VCs include digital proof mechanisms that enable verification. One of these mechanisms is digital signatures which are used to prove credential validity. VCs are issued by Issuers to Holders and often contain an Issuer DID that resolves to a DID document. The DID document references a public key in order to check the Issuer’s cryptographic signature, proving the authenticity of the Issuer. VPs contain one or more VCs and they can be presented by Holders to Verifiers who can then cryptographically verify the authenticity of the Issuer. ## Schemas Credential Schemas are implemented as JSON schemas and are a type of metadata that provide a standardised way to define the structure and validation rules for VCs. It serves as a blueprint, allowing applications to ensure that data conforms to a specific structure and set of rules, and they promote interoperability. ## Credential Lifecycle Typically a VC has a lifecycle comprised of the following events: * **Issuance**: An Issuer issues a signed VC to a Holder who consents to receiving the VC in their digital wallet. There are different modes of issuance: * The VC is pushed from an Issuer. Here, a thorough consent and Issuer verification mechanism is important to protect the Holder from receiving unsolicited content by unknown Issuers. * An entity (such as a Holder) can proactively request a VC to be issued to them. * Issuance of a VC can be done instantaneously or deferred until a pre-determined time. * **Verification**: A Holder will present a VC for verification to a Verifier. By implementing the W3C VP format, credentials can be combined to fulfil a request for credentials, and Holders can implement selective disclosure if available. * **Revocation or suspension**: An Issuer may revoke or suspend a credential and register its new status in a Verifiable Registry, available to Verifiers upon verification. This makes verification of credentials faster and more accurate. Verifiable Registries can be hosted in a number of different ways: * Centralised (e.g. via a provider) * Decentralised (e.g. using a distributed ledger) # Decentralised Identifiers (DIDs) Decentralised identifiers (DIDs) are a type of digital identifier that can be associated with any subject. The subject can be a: person, device, organisation or thing. Whatever type of subject the DID is linked to, they are controlled by the creator who can choose where and when to use them. The difference between other commonly used identifiers (e.g. email, twitter handle) and DIDs is that the former are controlled by someone else (email provider, Twitter) and can be taken away. DIDs solve that issue, which makes them a very important cornerstone for digital identity. A DID may have one or more DID controllers who contribute to changes made to a DID document. Meeco's framework does not prohibit the usage of any property in the DID document by the DID controller, this is to aid future extensibility and versatility. Key characteristics of a DID include: * Decentralised: they are not managed or issued by a central authority. * Persistent: once created, they are permanent and do not rely on an organisation to manage them (as opposed to DNS, email, etc). * Cryptographically verifiable: designed to be associated with cryptographic keys and as such allow someone to prove control over the DID. * Resolvable: allow any party to discover information about it to give it meaning. See [Use Cases and Requirements for Decentralized Identifiers, W3C](https://www.w3.org/TR/did-use-cases/) for more information. ## DID Methods There are many DID methods in use today (+200 at the time writing). Determining which DID method to use at any one time generally depends on its intended use case. An important consideration is whether the DID is going to identify a natural person (NP) or legal entity (LE). When identifying NPs, privacy regulations come into effect and, generally speaking, it is always safer to use a DID method that does not rely on a verifiable data registry (VDR). On the other hand, for LEs, it is rather useful to use a publicly accessible VDR that allows secure resolution of a DID. DID method specifications are developed to define DID methods, including specific operations. These operations include how the DIDs and DID documents are created, resolved, updated, and deactivated. ### Universal Resolver Meeco supports DID resolving for various DID methods via a system based on the Universal Resolver (UR). The UR has been designed and is managed by the [DIF Identifiers & Discovery Working Group](https://identity.foundation/working-groups/identifiers-discovery.html) and can be contributed to by individuals working in the discipline. The UR enables systems to resolve DIDs across many different DID methods. This allows system implementers to be DID-agnostic and provide seamless workflows between ecosystems. ## How are DIDs used? While DIDs are used to identify a particular subject, personally identifiable information (PII) is not generally associated with the DID or associated DID document. Keeping in mind that a DID is a URI and as such a formatted combination of letters, numbers and specific symbols, a subject’s DID does not include the subject’s name, location or other identifying attributes. It is advised by W3C that, when PII associated with a subject needs to be managed or shared, it should be done so via a Verifiable Credential (VC) or service endpoints controlled by the DID subject. This process ensures that the privacy of the subject is maintained and the control over data sharing and exposure remains with the subject itself. Items such as VCs can be associated with DIDs to ensure the subject can maintain and manage their PII, however only the subject can read the data inside the VC. The subject can always share the VC with another party, and in that transaction the subject will grant access to the party to read their associated DID document. For detailed information on Meeco’s DID implementations see our [DID API documentation](/svx-v3/guides/api-guides/dids). # Keys The Key component of Secure Value Exchange (SVX) comprises a service for storing and retrieving encryption keys, along with a library that assists in the data encryption process. These tools are designed to enhance security and privacy in data management across different states - at rest, in transit, or during exchange. Our system works well with standard cryptography libraries, providing both flexibility and ease of integration. ## Keystore The Keystore service within SVX is a practical tool designed to assist users and organisations in storing and retrieving encrypted keys. Its primary function is to provide convenience, ensuring that your keys are accessible wherever you need them. It simplifies the task of secure key management, making it easier to access your keys across various platforms and devices. ## Key Hierarchy In any secure communication system, the role of cryptographic keys is paramount. They facilitate the encryption and decryption of data, ensuring the privacy and integrity of the information exchanged. Within our system, we use a specific hierarchy of cryptographic keys, each with a distinct purpose and responsibility. The keys' functionality is designed in line with the guidelines from the [National Institute of Standards and Technology (NIST)](https://csrc.nist.gov/projects/key-management/key-management-guidelines), thus providing a reliable and secure architecture. The roles and responsibilities of various keys are as follows: * **Master Encryption Key (MEK)**: Derived from a user-generated passphrase using a secure key derivation function, the MEK is responsible for encrypting the Key Encryption Key (KEK). It is kept solely by each user and never shared or transmitted. * **Key Encryption Key (KEK)**: KEKs are keys that are used for encrypting and decrypting other encryption keys, except for the MEK. They play a critical role in key management processes, including secure key storage and key distribution. * **Keypair**: Comprising a private and a public key, a keypair is used for asymmetric encryption and digital signature purposes. It controls a Decentralized Identifier (DID), with the private key kept confidential and the public key shared openly. * **Data Encryption Key (DEK)**: DEKs are used specifically for encrypting and decrypting data. There are two types of DEKs: * DEK for personal data: Utilised to safeguard the user's personal data by encrypting and decrypting data exchanged with a secure storage solution such as the SVX [Vault](/svx-v3/platform/vault). * DEK for sharing data: Used for encrypting and decrypting data that is shared or exchanged with another user. In SVX, a well-structured key hierarchy for effective key management and secure access to encrypted data has been implemented. The hierarchy operates on a tiered principle, meaning access to encrypted data depends on obtaining each key in the sequence. Here is how it works: When it comes to storing data securely, the process begins with a Data Encryption Key (DEK) and a Keypair. These keys are necessary for encrypting and securing the data. Following this, a Key Encryption Key (KEK) is generated. The KEK is a new symmetric key, and its purpose is to encrypt the DEK and the private key of the Keypair. To ensure the security of the KEK, it is further encrypted by a symmetric key known as the Master Encryption Key (MEK). The MEK is derived from the user's input via a process called a Password-Based Key Derivation Function (PBKDF2). This user input is known as the Passphrase/Password Derived Key (PDK). In essence, this hierarchy provides a structured and secure method for managing keys and accessing encrypted data, with each key playing a critical role in the overall process. ## Cryppo The final element of our key service is Cryppo, a library available in different programming languages, designed to facilitate the encryption and decryption of data. More than just a tool for data protection, Cryppo is also a crucial ally in maintaining data consistency. Cryppo's main role is to ensure that data, when encrypted and decrypted, adheres to the format expected by the SVX [Vault](/svx-v3/platform/vault). By standardising the data structure, Cryppo ensures that all information is stored uniformly, enhancing the reliability and accessibility of the data. Essentially, Cryppo serves as a bridge between users and the Vault, overseeing the data's secure transition while maintaining its consistency. This results in a seamless interaction with the Vault, enabling users and organisations to protect their sensitive information without compromising its availability. # Tenants, Organisations, and End-Users Within Meeco’s Secure Value Exchange (SVX) platform, different entities have been developed for different purposes. Understanding the difference between these entities, how it maps to users and organisations is important, as it will help you to understand the responsibilities of each. It is worth noting that regardless of whether you are using Meeco’s APIs, or if you are interacting via our [Portal](/svx-v3/platform/portal), the different users and organisations are consistent across both. ## Users and Organisations Explained Throughout this documentation, the term ‘Users’ broadly refers to individuals interacting with the SVX platform, including our customers' customers and those engaging with various workflows. Within SVX, the term ‘End-users’ specifically denotes Wallet Holders and users associated with a Tenant (refer to the section below for further details). Please note that the term ‘Organisation’ is occasionally used throughout our documentation as a cover-all term for any enterprise, company, group, or association. When utilising SVX, ‘Organisation’ refers to a specific role played by an enterprise, company, group, or association undertaking actions within a Tenancy. ## Network Participants and their Role SVX network participants as follows: | Ecosystem Participant | Role | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Tenant | A Tenant is operated by an enterprise. Its main responsibility is the governance of its network, participating organisations, and end-users. | | Tenant Administrator | An individual (user) who has administrator access within a Tenant. A Tenant Administrator is responsible for the actions that take place within their Tenant, including the onboarding, management and governance of Organisations. | | Organisation | An Organisation participating in the ecosystem will typically take the role of a credential or data Issuer, Verifier, or both. Organisations connect to End-users to exchange data. | | Organisation Administrator | An individual (user) who has administrator access within an Organisation. An Organisation Administrator can use the Portal to manage the lifecycle of credentials and set up machine-to-machine access. | | End-User | End-users are associated with a Tenant and benefit from services offered by that Tenant including the ability to connect to Issuers, Verifiers, and create a vault. | For more information on how users and organisations form an ecosystem, see our [Ecosystems](/svx-v3/concepts/ecosystems) page. # Vault ## Vault Within Secure Value Exchange (SVX) is a secure storage solution called the Vault. The Vault is where users can store a range of data types including attributes, documents, Verifiable Credentials (VCs), and digital media. The Vault has been built to align with both [Privacy-by-Design (PbD)](/svx-v3/concepts/privacy-and-security-by-design) and [Security-by-Design (SbD)](/svx-v3/concepts/privacy-and-security-by-design) principles. The Vault has a [Zero Knowledge Value (ZKV)](/svx-v3/concepts/terminology#zero-value-knowledge-zvk) architecture, which means all data values are end-to-end encrypted with only the metadata in plain text. By enabling plain text metadata an extensive range of use-cases are possible without accessing personally identifiable information (PII). For example, it is possible to request and exchange data without having direct access to it. It also allows for an extensible data schema and the addition of semantic labels. All data values are encrypted in transit and at rest with unique cryptographic keys managed by the user of that Vault. Additionally, all data values are assigned a Universally Unique Identifier (UUID) to guard against correlation when the data is shared or exchanged. This approach also supports Progressive Disclosure and other data minimisation use cases. To enable the sharing of data, the Vault comprises of four key elements: Slots, Items, Connections and Shares. Together, these elements provide users with flexibility, customisation and control of their data. Below is an introduction to these elements, for further details see our [Vault API documentation](/svx-v3/guides/api-guides/vault). ### Slots Slots are the smallest data entity in the Vault. Each Slot represents a field that is seen by Vault users when creating an Item. Each Slot has a name (machine-readable non-empty string), a label, and a value, for example: * Name: policy\_number * Label: Policy number * Value\*: Numerical \* Values can be strings, dates, or numbers, but also binaries such as images or documents. Values are always encrypted. ### Items Items form the basis for every set of data stored in the Vault. In order for a user to store data (text, a document, an image etc.) they must first select an Item Template from the available options. These templates are made available by the ecosystem facilitator and will appear in user Vaults that are associated with the ecosystem. Templates allow users to categorise, sort and manage the data they store. They are a starting point and can easily be extended with other attributes. After selecting an Item Template, the Vault user can add descriptive information about the data being stored, for example: * Their house insurance policy number, and * The date the policy is due to expire They also have the option to attach files and assign tags (for ease of filtering). Once saved, a new Item will appear in the user's Vault. ### Connections For Vault users to Share their Items, they must establish Connections with other Vault users. A Connection is established via an invitation flow which requires users to consent to the Connection being made. Connections can be cancelled at any time by either Vault user. Connections can also be governed by business rules, for example, maintain the Connection for the duration of being a customer, or until a service has been completed. ### Shares The sharing of data occurs when a Vault user creates a Share and defines the following parameters: * Which Item will be shared * Whether all or specific Slots within an Item will be shared * The Connection who will receive the share * The length of time the Item will be shared * Whether the Item can be On-Shared When a Share is initiated by a Vault user, the recipient (Connection) must give consent to receiving the Share. This consent-based data sharing model ensures Vault users are not involuntarily receiving data from other users. This provides additional data governance and audit. An additional feature to Shares is On-Shares where Vault users can specify if the recipient of a Share can then On-Share the Item with another Vault user. A key feature of On-Sharing is that the original Item owner maintains the Share parameters and any changes they make will propagate down through any On-Shares. ### Account Delegation The Account Delegation feature enables Vault users to provide full access or read-only access to their data to a trusted individual. An example where this feature may be employed is when a Vault user (a child or an aging parent) requires assistance when managing or exchanging their data with other parties. With the Vault, they are able to ask a trusted individual to be a delegate of their Vault. > **Note** that in almost all cases we recommend using Shares and On-Shares to give access to other users as it gives much more granular control over the data shared to another user. However, there are circumstances where Account Delegation is more practical. Consider the use case(s) that you are developing when selecting different features. ## Implementation and Integration Our Vault technology can be embedded in existing (front- and backend) applications such as mobile banking apps, web portals or back-up services with authentication via an OIDC provider. Convert data from onboarding to any product or service to a Vault to enable customer control and direct collaboration. This approach minimises the amount of times a customer has to re-key information. It also increases security and decreases fraud and mistakes. Importantly, it provides a peer-2-peer connection with customers for secure communications, notifications and data sharing. ### End-user Vault An End-user Vault is accessed, managed and controlled by one single user. End-user Vaults can be made available to participants within an ecosystem including, but not limited to: customers of a bank, students of an education institute, members of an association, or, individuals can manage their own Vault and establish Connections without being part of an established ecosystem. ### Enterprise Vault An Enterprise Vault (EV) is a secure service similar to an End-user Vault but with added functionality tailored to enterprises. *Enterprise* refers to any entity, for example a company, government, or association. For further details on EVs, see the [Enterprise Vault](/svx-v3/platform/vault/enterprise-vault) information page. ## Standards and Compliance For all European Union customers, data is hosted in Europe and is General Data Protection Regulation (GDPR) compliant. Speak to us about data sovereignty in other jurisdictions. # Enterprise Vault An Enterprise Vault (EV) is a secure service similar to an End-user Vault with added functionality tailored to enterprises. *Enterprise* refers to any entity, for example a company, government, or association. In the context of an EV, an “Organisation” is the entity that controls and manages their own EV. ## Functionalities The key functionalities of an Enterprise Vault are as follows: * [Items](/svx-v3/guides/api-guides/vault/items-and-slots), [Slots](/svx-v3/guides/api-guides/vault/items-and-slots), [Connections](/svx-v3/guides/api-guides/vault/connections-and-sharing), [Sharing](/svx-v3/guides/api-guides/vault/connections-and-sharing), [Classifications](/svx-v3/guides/api-guides/vault/classification-hierarchies), [Attachments](/svx-v3/guides/api-guides/vault/attachments) (as per an End-user Vault). * Fined-grained consent capabilities to manage the sharing of data with end-users. * The Organisation that manages an EV can have one or more Administrators who are authorised to onboard and manage other Administrators. * The Administrator(s) of an EV can manage and deploy additional services that work harmoniously with the EV's features and functions. * Administrators, with the associated access rights, have access to [Items](/svx-v3/guides/api-guides/vault/items-and-slots), [Connections](/svx-v3/guides/api-guides/vault/connections-and-sharing) and [Shares](/svx-v3/guides/api-guides/vault/connections-and-sharing) in the EV. * Organisation Administrators have the ability to onboard third-party services (associated with the Organisation) to act on behalf of that Organisation. This enables third-party services access to [Items](/svx-v3/guides/api-guides/vault/items-and-slots), [Connections](/svx-v3/guides/api-guides/vault/connections-and-sharing) and [Shares](/svx-v3/guides/api-guides/vault/connections-and-sharing) within the EV in a secure, controlled way. * An Organisation can connect to any user or other Organisation via a Vault-to-Vault conenction in order to undertake various workflows. ## Services executed via an Enterprise Vault The following are examples of services the EV offers: * **Secure data storage**: Storage of data including, but not limited to: * raw data * structured data * verifiable data * self-attested data * semantic data * verifiable and verified data (including Verifiable Credentials) * documents * **Secure sharing**: Structured data shared in a persistent or one-off way, for example: a document or attachment. Shared data can also include a business rule that determines if the data can be edited/updated, or locked to prevent editing by the Organisation or other parties. * A specific implementation of secure sharing is the creation of an [Item](/svx-v3/guides/api-guides/vault/items-and-slots) pushed via a secure API to an End-user Vault, without storing the [Item](/svx-v3/guides/api-guides/vault/items-and-slots) in the EV. This allows the secure sharing of sensitive data from other systems without the need to maintain the [Item](/svx-v3/guides/api-guides/vault/items-and-slots) in the EV. * **Securely receiving**: Structured data from any authorised party (end-user or third-party) within an EV ecosystem. This enables easy integrations with other services. ## Interacting with the Enterprise Vault There are multiple ways to interact with and manage an EV, including: **SVX Portal**: The [Portal](/svx-v3/platform/portal) is a web application that enables Organisation Administrators to onboard, invite additional Organisation Administrators, and begin accessing Meeco's Vault API via a low-code interface. When using the EV via the Portal, Administrators can view [Items](/svx-v3/guides/api-guides/vault/items-and-slots), [Connections](/svx-v3/guides/api-guides/vault/connections-and-sharing) and [Shares](/svx-v3/guides/api-guides/vault/connections-and-sharing). It also provides a view of the End-users and other third-party services that the Organisation is connected to. **SVX API**: All functionality is available using the [SVX API (sandbox)](https://api-reference-sandbox.svx.exchange) to connect services. **Command Line Interface (CLI)**: Meeco provides a [CLI](/svx-v3/tools/meeco-cli) to facilitate interactation with the EV. **Onboarding to an Enterprise Vault**: To set up an EV, an authorised user must first create an Organisation. Note that setting up an Organisation will require either approval via the creation of a Meeco Licence, or via an ecosystem's Tenant Administrator. # Portal The Secure Value Exchange (SVX) Portal is a user-friendly interface that allows users to undertake processes enabled by the SVX API. Following an initial onboarding invitation, Tenant and Organisation Administrators can self-service in order to complete their desired workflows. Depending on their associated [Security Rights](/svx-v3/concepts/terminology#security-rights-srs), an Administrator can undertake the following tasks: * Manage their Tenant / Organisation * Invite and manage other Administrators * Utilise the Credential Service to: * Create and manage credential schemas * Create and manage credential templates * View issued and revoked credentials * Create and manage verification templates * View and manage verification requests * View and manage request responses * Utilise the Enterprise Vault to: * Create and manage connections * View items being shared * Create and manage Applications ### Tenants #### Role, Administrators & Activity The Portal enables enterprises to manage their own Tenancy. Once a Tenancy has been created, Tenant Administrators can onboard Organisations and invite Organisation Administrators to join. Tenant Administrators have access to [Credential Schemas](/svx-v3/guides/portal-tutorials/tenant-administrators/credential-schemas), [Applications](/svx-v3/guides/portal-tutorials/tenant-administrators/applications), [End Users](/svx-v3/guides/portal-tutorials/tenant-administrators/end-users), and management of their account. > **Note** Once a Credential Schema is defined it can be made available to Organisations that will issue credentials. For more information on Credential Schemas see the [Credential Schema tutorial](/svx-v3/guides/portal-tutorials/tenant-administrators/credential-schemas). #### Responsibilities During onboarding, all users of the Portal must agree to Meeco’s Terms and Conditions and Privacy Policy. It is the responsibility of the Tenant Administrator(s) to ensure the Organisations within their Tenancy are acting in an ethical, responsible manner. ### Organisations #### Role, Administrators & Activity When Organisations are onboarded to the Portal they are invited to join an existing Tenancy. As mentioned above, the Tenant governs the Tenancy in which the Organisation conducts business. Organisation Administrators manage the Organisation and, depending on their [Security Rights](/svx-v3/concepts/terminology#security-rights-srs), can action workflows associated with Credentials, their Enterprise Vault, Applications and account settings. When utilising credentials, Organisations can act as Issuers and/or Verifiers, thus allowing them to manage: * Credential Templates * Issued, revoked and verified credentials * Verification Templates * Verification Requests Each time an action is undertaken, Organisation Administrators can view and / or archive the item / occurrence. This provides Organisations with fine-grained reporting and transaction management capabilities. #### Responsibilities During onboarding, all users of the Portal must agree to Meeco’s [Terms and Conditions](https://www.meeco.me/terms) and [Privacy Policy](https://www.meeco.me/privacy). It is the responsibility of the Organisation Administrator(s) to ensure all Administrators are acting in an ethical, responsible manner. ### Credentials The Portal provides access to credential management in a simple, user-friendly way. It enables non-technical users to engage with our Verifiable Credential workflows via an intuitive interface. Our credential service utilises the [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model-2.0/) to ensure standardisation and interoperability with external systems. Additionally, when undertaking credential-based workflows via the Portal, users are engaging in industry leading privacy and security practices that are aligned with current specifications and regulations, specifically the Australian Privacy Principles and General Data Protection Regulation (GDPR) (for details see our [Privacy- and Security-by-design](/svx-v3/concepts/privacy-and-security-by-design) page). #### Credential Schemas The Portal provides Tenant Administrators with the option to create Credential Schemas within their Tenancy and make them available to Organisations. With access to a library of Credential Schemas, Organisations can specify which schema is required when creating Credential and Verification Templates. When Organisations within the same ecosystem are referencing the same schemas, credential issuance and verification is accurate and standardised. For further details on how to create and manage Credential Schemas, see the [Credential Schemas tutorial](/svx-v3/guides/portal-tutorials/tenant-administrators/credential-schemas). #### Credential Templates Organisations that issue credentials (Issuers) can create Credential Templates which form the base of the credentials they will issue. Credential Templates include the associated credential schema (which determines the information required from the Holder), and credential styling information which enables customisation of credential colour schemes and logos. For further details on how to create a Credential Template, see the [Credential Template tutorial](/svx-v3/guides/portal-tutorials/organisation-administrators/credential-templates). #### Issue credentials The issuance of credentials is made easy via the Portal by a simple step-by-step workflow. Issuers first select one of the Credential Templates they have created previously (see the [Credential Template tutorial](/svx-v3/guides/portal-tutorials/organisation-administrators/credential-templates) for details). The Credential Template defines the attributes that are required to be filled in. For example, a First Aid Certificate Credential Template might include attributes such as: * Student name * Student ID * Course ID * Subject code * Grade Once the Organisation Administrator has filled in all required attributes specific to the credential recipient (Holder) they are able to issue the credential. For further details on how to issue a credential, see the [Issue / Revoke Credentials tutorial](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/portal-tutorials/organisation-administrators/issue-revoke-credentials.md). #### Revoke credentials When revoking a credential, an Organisation Administrator simply locates the credential in the list of issued credentials, and selects the option to revoke. For further details on how to revoke a credential, see the [Issue / Revoke Credentials tutorial](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/portal-tutorials/organisation-administrators/issue-revoke-credentials.md). #### Verification Templates Organisations that verify credentials (Verifiers) can create Verification Templates which form the base of Verification Requests. Verification Templates include the associated credential schema (which determines the information required from the Holder), and if required, a specific Issuer of these credentials can be defined. For further details on how to create a Verification Template, see the [Verification Template tutorial](/svx-v3/guides/portal-tutorials/organisation-administrators/verification-templates). > **Note** Please note that we acknowledge the term [Verifiable Presentation](/svx-v3/concepts/terminology#verifiable-presentation) as commonly used in credential specifications, but for the purposes of our Portal, we refer to Verifiable Presentations as Verification Templates. #### Verification Requests In order to verify credentials via the Portal, an Organisation Administrator (Verifier) creates a new Verification Request. Each request requires the Organisation Administrator to select a Verification Template which defines the credential(s) required from the Holder for verification. Once a Verification Template has been selected, the Verifier can view the request in the form of a QR Code. The QR Code can be presented to a Holder in-person, or downloaded and shared via any form of digital sharing method. For further details on how to create a Verification Requests, see the [Verification Requests tutorial](/svx-v3/guides/portal-tutorials/organisation-administrators/verification-requests). ### Additional Credential Service Information For detailed information about our credential service, see our [Verifiable Credentials](https://www.meeco.me/verifiable-credentials) information page or our [API documentation](https://api-reference-sandbox.svx.exchange/). ### Enterprise Vault While the Enterprise Vault (EV) can be directly utilised via the SVX API, it can also be managed by Organisation Administrators via the Portal. By providing an interface to the EV, non-technical Administrators can easily create and manage connections, including the sharing of items on behalf of their Organisation. For further information, see the [Enterprise Vault](/svx-v3/platform/vault/enterprise-vault) overview page. #### Connections The EV allows Organisations to securely share data with end users via Vault-to-Vault connections. Organisation Administrators can invite end users to connect via a simple invitation workflow. After entering the connection’s full name into the system, they can generate an invitation code. This invitation code is then passed to the new connection which they enter into their own Vault-using application. On acceptance by the connection recipient, the connection between the two Vaults is established. For further details on establishing and managing connections, see the [Connections tutorial](/svx-v3/guides/portal-tutorials/organisation-administrators/connections). ### Additional Enterprise Vault Information For detailed information about our EV offering, see the [Enterprise Vault](/svx-v3/platform/vault/enterprise-vault) information page or our [API documentation](https://api-reference-sandbox.svx.exchange/). # Wallets # Holder Wallet The Holder Wallet (HW) is a key component of Meeco’s SVX Platform, designed to empower end users (Holders) to receive, claim, and manage issued Verifiable Credentials (VCs), as well as present them for verification. Accessible via the HW API, it is built on international standards and specifications to ensure interoperability across VC ecosystems. This enables Holders to securely share their information with trusted parties within global ecosystems that follow the same framework. By leveraging the HW, organisations can provide their customers with greater control over their data and the ability to share it seamlessly in everyday scenarios. #### Creating a HW To create a HW a user must first sign up to Meeco’s SVX Platform and register as a Tenant Administrator (TA). After receiving SVX login credentials, access to the SVX API and the Portal will be possible. The TA will need to create an Application, see the [Machine-2-Machine Communication](/svx-v3/guides/api-guides/machine-2-machine-communication) guide for API access or the [Applications](/svx-v3/guides/portal-tutorials/tenant-administrators/applications) guide if using the Portal. Once an Application has been created, a TA will need to provide Meeco’s SVX team with the following information: * Client ID * Client Secret From here, the SVX team will deploy a HW and an instance of the HW-FE connected with the Tenant’s application. Additionally, Tenant Administrators can specify which IdP they would like to associate with their HW. The IdP will enable end user (Holder) authentication at the time a Holder creates a wallet account via the HW-FE application. The IdP will then be configured to communicate with the HW (via the HW Gateway) and enable TAs visibility on the number of HW-FE users and their wallet IDs. > **Note** TAs can use the [HW-FE provided by Meeco](#holder-wallet-front-end-hw-fe) or opt for their own or a third-party application. #### Verifiable Credentials (VCs) Built on the international specifications [OpenID for Verifiable Credential Issuance (OID4VCI)](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) and [OpenID Connect for Verifiable Presentations (OID4VP)](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) the HW receives and presents VCs based on the [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/). As more organsiations and ecosystem operators adopt these specifications and standards, VC issuance, verification and Holder engagement becomes easier to initiate across platforms. #### Use Case Application As the HW is provided as an API, its application is virtually limitless. Multiple HW instances can be utilised within a use case to distinguish between different Holders and their respective workflows. Additionally, given the wide variety of Verifiable Credentials (VCs) that can be issued and verified, its use extends across diverse industries and sectors. For more information on use cases where the HW plays a pivotal role in the receiving, management and presentation of VCs, see our [Use Case Videos](https://www.meeco.me/resources/use-case-videos) via the Meeco website. #### Diagram The diagram below provides a high-level overview of how the HW can interact with different services.
Holder Wallet service diagram.
> **Note** As the HW is delivered as an API, all updates and changes are instant. New versions of the API will be released intermittently with associated updates communicated with customers promptly. ### Holder Wallet Gateway The Holder Wallet Gateway sits in front of the HW and is a separate application designed to restrict API calls and make the HW API more secure. It does this by providing an authentication layer to the HW. The software used to create this Gateway is [KrakenD](https://www.krakend.io/) and its purpose is to manage API traffic, implement rate limiting, instill authentication measures, and serve as a control point for managing API requests. This layer can also enforce security policies and provide additional logging and monitoring capabilities. Endpoints exist in the HW that are required to be publicly available. This is to ensure [OID4VCI](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) and [OID4VP](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) compliance, and for key and metadata lookup. There are also endpoints that must remain private when controlling and creating credential offers. The Gateway handles the associated authentication to only allow authorised requests to call these private endpoints. ### Holder Wallet Front End (HW-FE) As HWs are primarily designed for use by people, it is recommended that a user-friendly interface is developed to facilitate wallet interactions. This interface can be implemented as a browser extension, a desktop application, or, more commonly, a mobile wallet app. Within SVX, the Holder Cloud Wallet (API) SDK allows customers to build their own wallet UI, plugins, or other integrations whilst utilising all wallet functionality. Meeco has also developed a front-end mobile application (reference implementation) for the HW titled the Meeco Wallet. This mobile app is available for SVX customers when undertaking POCs and Pilot programs. Additionally, the user interface (UI) is somewhat customisable, including the addition of logos, colour themes and feature images. To view the functionality of the Meeco Wallet, see the [Wallet tutorials](https://github.com/Meeco/docs/blob/archive/svx-3.x/platform/wallet/guides/wallet-tutorials/README.md). # Organisation Wallet The Organisation Wallet (OW) is a component of Meeco’s SVX Platform that enables organisations to issue, verify and manage Verifiable Credentials (VCs). The OW is accessible via the API with the same name. The OW is built on international standards and specifications that enable interoperability across VC ecosystems. Organisations can integrate the OW into existing systems and processes and can securely store VCs with Meeco’s secure storage offering, the Vault. The OW’s cryptographic keys are also managed by Meeco’s proprietary key management service, the Keystore. #### Accessing an Organisation Wallet To access an OW a user must first sign up to Meeco’s SVX Platform. After receiving SVX login credentials, access to the OW API will be granted. When setting up the OW, the creation of an Application will be required. See the [Machine-2-Machine Communication](https://github.com/Meeco/docs/blob/archive/svx-3.x/platform/wallet/machine-2-machine-communication.md) guide for API access or the [Applications](https://github.com/Meeco/docs/blob/archive/svx-3.x/platform/wallet/portal-tutorials/organisation-adminsitrators/applications.md) guide if using the Portal. #### Verifiable Credentials (VCs) Built on the international specifications [OpenID for Verifiable Credential Issuance (OID4VCI)](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) and [OpenID Connect for Verifiable Presentations (OID4VP)](https://openid.net/specs/openid-connect-4-verifiable-presentations-1_0-07.html) the OW issues and verifies VCs based on the [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model-2.0/). As more organsiations and ecosystem operators adopt these specifications and standards, VC issuance, verification and Holder engagement becomes easier to initiate across platforms. Included in the OW offering is the creation and management of credential schemas and credential types. This ensures Issuers and Verifiers have a common understanding of the VCs they are interacting with. It ensures that VCs being issued and verified are aligned with the same specifications and can be recognised by all parties within the ecosystem. #### Use Case Application As the OW is delivered as an API, its application in use cases is endless. Multiple OWs can be used in a use case to differentiate Issuers and Verifiers, and the workflows they undertake. Additionally, as the types of VCs that can be issued and verified are vast, use cases extend to all disciplines and sectors. As the OW is delivered as an API, the development of a UI is possible. This UI can be delivered in the form of a browser extension, desktop app, or mobile wallet app. It can also be integrated into existing databases, records management systems as well as standalone devices, including verification systems. #### Diagram The diagram below provides a high-level overview of how the OW can interact with different services. > **Note** As the OW is delivered as an API, all updates and changes are instant. New versions of the API will be released intermittently with associated updates communicated with customers promptly. ### Organisation Wallet Gateway In front of the OW sits an API Gateway. This Gateway provides an authentication layer to the OW. The software used to create this Gateway is [KrakenD](https://www.krakend.io/) and its purpose is to manage API traffic, implement rate limiting, instill authentication measures, and serve as a control point for managing API requests. This layer can also enforce security policies and provide additional logging and monitoring capabilities. Endpoints exist in the OW that are required to be publicly available. This is to ensure [OID4VCI](https://openid.net/specs/openid-4-verifiable-credential-issuance-1_0.html) and [OID4VP](https://openid.net/specs/openid-connect-4-verifiable-presentations-1_0-07.html) compliance, and for key and metadata lookup. There are also endpoints that must remain private when controlling and creating credential offers. The Gateway handles the associated authentication to only allow authorised requests to call these private endpoints. ### Issuer and Verifier Template Sites To enable Organisations to undertake actions associated with issuing and verifying credentials in a real-world scenario, template websites have been developed for customer use. These template websites are built using the OW API to enable quick use case deployment. Each of the issuance and verification sites are multi-page sites that facilitate the following workflows: #### Issuance * User authentication via a login page. * Option to issue verifiable credentials of various formats (based on what the Organisation has prepared). * A form to capture the associated Holder’s information. * The generation of a QR Code (desktop) or deeplink (mobile) to present the credential offer. #### Verification * Option to verify credentials of various formats (based on what the Organisation has prepared). * Presentation of a list of attributes required from the Holder. * The generation of a QR Code (desktop) or deeplink (mobile) to present the request. * Notification page on successful / unsuccessful verification of credential(s). These pages can be added to existing user journeys by navigating to and from existing websites. It is also possible to customise the websites' user interface (UI). This includes the addition of custom text, logos, colour themes and feature images. # Supported Standards Meeco is actively following, and where possible, contributing in standardisation efforts of the leading groups in the identity and personal data space. This page lists the currently supported standards within the Secure Value Exchange (SVX) platform. ## Standard Bodies * [Decentralized Identity Foundation (DIF)](https://identity.foundation/) * [European Blockchain (EBSI)](https://ec.europa.eu/ebsi) * [HBAR Foundation](https://hbarfoundation.org) * [Internet Assigned Numbers Authority (IANA)](https://www.iana.org) * [Internet Engineering Task Force (IETF)](https://www.ietf.org/) * [OpenID Foundation (OIDF)](https://openid.net/foundation/) * [World Wide Web Consortium (W3C)](https://www.w3.org/) ## Standards | Component | Open Specifications / Standards | Standard Body | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- | | Credential Data Model | [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model) | W3C | | Credential Data Format | [JSON Web Token VC (JWT-VC)](https://www.w3.org/TR/vc-data-model/#json-web-token) - signed as JWS ([RFC7515](https://datatracker.ietf.org/doc/html/rfc7515)) | W3C, IETF | | Credential Presentation | [Presentation Exchange v2](https://identity.foundation/presentation-exchange/spec/v2.0.0/) | DIF | |

Credential Presentation
Transfer Protocol

| [OpenID for Verifiable Presentations](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) | OIDF | | Credential JSON Schema | [Verifiable Credentials JSON Schema Specification](https://www.w3.org/TR/vc-json-schema/) | W3C | | DID Authentication | [Self-Issued OpenID Provider v2](https://openid.net/specs/openid-connect-self-issued-v2-1_0.html) | OIDF | | Identifier Data Model | [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/) | W3C | | Entity Identifier (NP) | [did:key](https://w3c-ccg.github.io/did-method-key/) | W3C | | Entity Identifier (NP) | [did:jwk](https://github.com/quartzjer/did-jwk/blob/main/spec.md) | - | | Entity Identifier (NP,LE) | [did:ebsi](https://ec.europa.eu/digital-building-blocks/wikis/display/EBSIDOC/EBSI+DID+Method) | EBSI | | Entity Identifier (NP,LE) | [did:hedera](https://github.com/hashgraph/did-method/blob/master/did-method-specification.md) | HBAR | | Entity Identifier (LE) | [did:web](https://github.com/w3c-ccg/did-method-web) | W3C | | Revocation | [Verifiable Credential Status List 2021](https://www.w3.org/TR/vc-status-list/) | DIF | | M2M/User Authentication | [The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749) - Code flow, client credentials flow | IETF | | User Authentication | [Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636) - Code flow | IETF | ## Supported Algorithms ### JWS Signature The following key types are supported for JWS verification. The subset of supported "JWS Algorithms" are part of [IANA - JSON Web Signature Algorithms registry](https://www.iana.org/assignments/jose/jose.xhtml#web-signature-encryption-algorithms). | JWS Algorithm | Key Type | | ------------- | --------------------------------- | | ES256 | ECDSA using P-256 and SHA-256 | | ES256K | ECDSA using secp256k1 and SHA-256 | | EdDSA | EdDSA using Ed25519 and SHA-256 | ### Master Encryption Key Algorithms The following algorithms are supported when generating derived keys. Used as defined in [NIST - Master Key](https://csrc.nist.gov/glossary/term/master_key). | Key Type | | ---------- | | PBKDF2HMAC | ### Key Encryption Algorithms The following algorithms are supported when encrypting other keys at rest and in transit. Used as defined in [NIST - Key-Encryption-Key](https://csrc.nist.gov/glossary/term/key_encryption_key). | Key Type | | ----------- | | AES-256-GCM | ### Keypairs The following keypair algorithms are supported for exchanging keys between parties. Used as defined in [NIST - Key pair](https://csrc.nist.gov/glossary/term/key_pair). | Key Type | | -------- | | RSA-4096 | ### Data Encryption Algorithms The following algorithms are supported when encrypting data at rest and in transit. Used as defined in [NIST - Data Encryption Key](https://csrc.nist.gov/glossary/term/data_encryption_key). | Key Type | | ----------- | | AES-256-GCM | ## Supported OAuth Authentication Flows The following flows are supported by SVX: ### OAuth Code Flow & PKCE The [Portal](/svx-v3/platform/portal) uses a code flow in conjunction with Proof Key for Code Exchange (PKCE) for secure authentication of users (Administrators) logging into the Portal. ### Client Credentials Flow Organisations building services on top of the SVX API can use the [Portal](/svx-v3/platform/portal) to create an application to enable machine-to-machine communication. The application allows access to a Client ID and Secret to perform the client credentials flow. The access token enables organisations to access the resources linked to that organisation. # Onboarding to SVX To onboard to Secure Value Exchange (SVX) you will first need to sign up. Navigate to our [sign up form](https://www.meeco.me/signup) to gain access to our Sandbox. Once your access has been approved, you will be able to [log in to the SVX Portal](https://portal-sandbox.securevalueexchange.com/login). From here you can: * Use the Portal UI to manage workflows, and * Directly access the SVX Sandbox API. ### Using the Portal UI Navigate to the [Portal login page](https://portal-sandbox.securevalueexchange.com/login) and log in using your SVX credentials. Refer to the [Portal tutorials](/svx-v3/guides/portal-tutorials) where you can find step-by-step instructions to navigate the Portal and manage a Tenancy and / or an Organisation. ### Accessing the SVX Sandbox API To directly access the SVX Sandbox API you will need to follow the steps below: **1. Access the SVX Sandbox API documentation:** Navigate to the [SVX Sandbox API documentation](https://api-reference-sandbox.svx.exchange/). At the top of the landing page, you will see the OpenAPI3 specification. Download the specification and import it into [Postman](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/). > **Note** To download the OpenAPI3 specification into Postman, follow these simple steps: > > 1. Download the specification from the [API documentation landing page](https://api-reference-sandbox.svx.exchange/) > 2. Open Postman > 3. Import the downloaded .json file **2. Retrieve a Personal Access Token** Open Postman and create a new request by clicking on the *New* button in the upper-left corner. Navigate to the *Authorization* tab, which is located below the URL field. In the *Authorization* tab, select *OAuth 2.0* from the *Type* dropdown menu. Fill in the OAuth 2.0 Access Token Request Details: ```bash Grant Type: Authorization Code with PKCE Auth Url: https://login-sandbox.securevalueexchange.com/oauth2/auth Access Token URL: https://login-sandbox.securevalueexchange.com/oauth2/token Client ID: ed3d2366-0fb6-406e-ae72-afd7634e6c9f Scope: openid profile email offline_access ``` After filling in the required details, click on the *Request Token* button. This will initiate the OAuth 2.0 authentication process. You will be redirected to the authorisation page of the service you are connecting to. Log in using your SVX login credentials. After successful authorisation, you will be redirected back to Postman, and the personal access token will be automatically saved. > **Note** Your Personal Access Token will expire after 1 hour. Just like the Application Token, you will be required to refresh it to maintain access. **3. Refresh your Personal Access Token** To refresh the Personal Access Token, you need to make a `POST` request to the OAuth2 token endpoint with a valid refresh token and your client and tenant IDs. ```bash curl 'https://login-sandbox.securevalueexchange.com/oauth2/token' \ -H 'content-type: application/x-www-form-urlencoded' \ --data-raw 'grant_type=refresh_token&refresh_token=existing_token&client_id=ed3d2366-0fb6-406e-ae72-afd7634e6c9f&tenant_id=32a08dc4-ad7f-491a-a06c-3284592a3737' \ --compressed ``` Make sure to replace `existing_token`, `client_id`, and `tenant_id` with your specific values. **4. Access the SVX Sandbox API** With the obtained personal access token, you can now use the SVX Sandbox API. For example, if you want to access the `me` endpoint, use the following cURL command: ```bash curl --location 'https://api-sandbox.svx.exchange/me' \ --header 'Meeco-Organisation-Id: YOUR_ORGANISATION_ID' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` Replace `YOUR_ORGANISATION_ID` with the relevant ID for your organisation, and `YOUR_ACCESS_TOKEN` with the token obtained in the previous step. You should now be able to successfully access the SVX Sandbox API using the provided authorisation token. For additional support, review the [API Guides](/svx-v3/guides/api-guides) or contact the [Service Desk](https://meecosystem.atlassian.net/servicedesk/customer/portal/4). # API Guides The following are step-by-step guides to the SVX API. # Credentials The following are step-by-step guides and contextual information relating to credential management via the SVX API. # Credential Schemas Credential schemas are used to define the structure of the claims of a verifiable credential (VC) and are associated with the [Data Schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property of a credential. Schemas use the [Verifiable Credentials JSON Schema](https://www.w3.org/TR/vc-json-schema/) specification, published by the W3C Credentials Working Group. Using schemas in the credential workflow allows Tenants, Organisations and users to: * Agree on the structure of data and facilitate data exchange * Extract information from the schema It is possible to create a credential without specifying a schema via the API, however, when using Meeco's Enterprise Portal to create credentials, this step is mandatory. In the Enterprise Portal, a user is required to upload a schema file which is then visually displayed as a form. A credential schema, once published, is versioned and made available via a public URL. This allows anyone to validate it at any point in time. ## Prerequisites * Verifiable Credential JSON Schema ### Verifiable Credential JSON Schema Each VC JSON Schema consists of the following mandatory attributes: * Name - A locally unique identifier to address the VC schema. * JSON Schema – Object that describes the schema the credential is validated against. [JSON schemas](https://json-schema.org/) are plain JSON objects that cosist of following mandatory attributes (at the top level): * `$schema` - The schema specification used (e.g. `https://json-schema.org/draft/2019-09/schema`) * `required` – Array of required properties. Array MUST include `id`. * `additionalProperties` – MUST be `false` * `type` – MUST be `object` Below is an example JSON schema. Note that all the attributes contained within a JSON schema will be used to form a credential. Attributes can be customised, and those that appear in the example below are indicative of possible options. ```bash { "$schema": "https://json-schema.org/draft/2019-09/schema", "title": "Example", "description": "Example", "type": "object", "properties": { "id": { "type": "string", } }, "required": ["id"], "additionalProperties": false, } ``` Note that the `$id` property of the JSON Schema is set by the platform. When one is present in the schema, it will be overridden. Also note that `https://json-schema.org/draft/2020-12/schema` is not supported at this point in time. ## Who can undertake this operation? Credential schemas are created and managed by Tenant Administrators who can assign them to Organisations. An Organisation can list the credential schemas that are assigned to them. Anyone can read the JSON schema (via a separate endpoint) that is part of the credential schema object. ## Create Credential Schema Creation of a credential schema. **Endpoint** ```bash POST /schemas ``` **Request** * Name – Name of the credential schema * JSON Schema - JSON schema file * List of organisations - Organisations where this credential schema can be used (optional) **Response** The response received is a credential schema object. Upon creation, version `1.0` is assigned. ## Read Credential Schemas Retrieve a list of credential schemas. **Endpoint** ```bash GET /schemas ``` **Request** * Organisation (header) **Response** A list of credential schema objects available to the user. In the context of an Organisation, the `organization_ids` attribute contains only one item: caller organisation ID. ## Update Credential Schema Update an existing credential schema by ID. Note that in this version, the schema cannot be updated. **Endpoint:** ```bash PUT /schemas/{id} ``` **Request** * The ID of the credential schema * Name – Name of the credential schema * List of organisations - Organisations where this credential schema can be used (optional) **Response** The updated credential schema object. ## Read Verifiable Credential JSON Schema A public endpoint that returns the JSON schema file. No authentication necessary. **Endpoint** ```bash GET /schemas/{id}/{version}/schema.json ``` **Request** * Id – ID of the Credential Schema * Version – Version of the credential schema **Response** Returns JSON schema for a credential schema. # Credential Types Credential types enable Organisations to select a [Credential Schema](/svx-v3/guides/api-guides/credentials/credential-schemas) when preparing credentials to be issued. They also allow Organisations to define the visual appearance of the credential which can reflect the Organisation's branding requirements. Credential types are used in both the Meeco Enterprise Portal and Meeco Wallet. Please note that in the Enterprise Portal, credential types are referred to as Credential Templates. ## Prerequisites * [Credential Schema](/svx-v3/guides/api-guides/credentials/credential-schemas) ## Who can undertake this operation? Credential types are created and managed by an Organisation Administrator. ## Create Credential Type Creation of a credential type. **Endpoint** ```bash POST /credential_types ``` **Request** * Name – Name of the credential type * Credential Schema - The associated credential schema * Style * Text Colour * Background Colour – Background colour for the credential (CSS styles supported) * Logo – Logo displayed in the top left corner of the credential **Response** The credential type object that is created. # Issue Credentials Issuing a credential is the first operation in the [Verifiable Credential (VC)](https://www.w3.org/TR/vc-data-model/#lifecycle-details) workflow. It enables the Issuer to create a credential so it can be delivered to the subject of the credential. The supported options when creating a credential are: * Generating a credential – Generates an (unsigned) credential that requires signing. * Issuing a credential – A credential is generated and signed with keys managed on the platform. The outcome of both of these options is a JSON formatted VC with a system-generated unique ID and an issuance date. ## Prerequisites The following items are required in order for a credential to be created and issued: * [Credential Schema](/svx-v3/guides/api-guides/credentials/credential-schemas) – the [data schema](https://www.w3.org/TR/vc-data-model/#data-schemas) of the credential * [Credential Type](/svx-v3/guides/api-guides/credentials/credential-types) * [DID](/svx-v3/guides/api-guides/dids/did-methods) ## Who can undertake this operation? Any Organisation that has been onboarded to a Tenancy (by the associated Tenant), and has been assigned the role of an Issuer. ## Generate a credential Generating a credential requires issuance data and data related to the credential subject. This data is structured following the data model of [W3C Verifiable Credential Core Data Model](https://www.w3.org/TR/vc-data-model/#core-data-model) in combination with the structure of the chosen credential schema. The following endpoint resolves the associated DIDs and performs a number of coherency checks. The result is a JWT ready to be signed. **Endpoint** ```bash POST /credentials/generate ``` **Request** The request contains the following data: * [Credential Type](/svx-v3/guides/api-guides/credentials/credential-types) * Issuer * DID – Fully qualified DID string * Name – Name of the issuer (optional) * Claims – Maps to the `credentialSubject` attribute of a credential * Subject DID – Typically, the `id` property contains the DID of the subject * Expiration date – Datetime after which the credential expires * Revocable – If true, the generated credential can be revoked later on. **Response** The response is the credential object that is generated. This contains: * ID of the credential * Unsigned credential in `vc-jwt` data format * Metadata # Presentation Definitions Presentation definitions define which credential(s) a Verifier requests and for what purpose. Each selected credential is comprised of a [credential schema](/svx-v3/guides/api-guides/credentials/credential-schemas) and the associated Issuer. The resulting object is conformant with the [W3C Presentation Exchange 1.0](https://identity.foundation/presentation-exchange/spec/v1.0.0/) specification and is used when generating a [Verification Request](/svx-v3/guides/api-guides/openid-connect/oidc4vp). ## Prerequisites * [Verifiable Credential JSON Schema](/svx-v3/guides/api-guides/credentials/credential-schemas) * [Issuer DID](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/api-guides/credentials/dids/did-methods.md) (optional) ## Who can undertake this operation? A presentation definiton is created by an Organisation. ## Create Presentation Definition Creation of a presentation definitions for an Organisation. **Endpoint** ```bash POST /presentation_definitions ``` **Request** * Organisation (header) * Name * Purpose * List of required credentials. For each, the following is defined: * Name * Purpose * Verifiable Credential JSON Schema URL * Issuer DID **Response** A presentation definition object is created. This presentation definition is associated with the pre-defined credential schema and the Organisation that initiated its creation. ## Read Presentation Definitions ### List Retrieve a list of presentation definitions owned by an Organisation. **Endpoint** ```bash GET /presentation_definitions ``` **Request** * Organisation (header) * Filters (optional): * Status **Response** List of presentation definitons managed by this Organisation. ### One Object Retrieve a presentation definition by ID. The resulting object needs to be owned by the Organisation that is making the request. **Endpoint** ```bash POST /presentation_definitions/{id} ``` **Request** * Presentation Definition ID * Organisation (header) **Response** A presentation definition object. ## Archive Presentation Definition A presentation definition can be archived and restored. When a presentation definition has been archived, it cannot be used in the verification request workflow. **Endpoint** ```bash PUT /presentation_definitions/{id} ``` **Request** * Presentation Definition ID * Organisation (header) **Response** The updated presentation definition status will be returned, either: * `is_archived: false` - For active or restored presentation definitions * `is_archived: true` - For archived presentation definitions ## Read Presentation Definition JSON Public endpoint that returns the JSON representation of a presentation definition, following the [W3C Presentation Exchange 1.0](https://identity.foundation/presentation-exchange/spec/v1.0.0/) specification. **Endpoint** ```bash GET /presentation_definitions/{id}/definition.json ``` **Request** * Presentation Definition ID * Organisation (header) **Response** Returns a JSON schema for a presentation definition. # Presentations A presentation, short for [Verifiable Presentation](https://www.w3.org/TR/vc-data-model/#presentations), is a data model that allows a Holder of [Verifiable Credentials (VCs)](https://www.w3.org/TR/vc-data-model/#credentials) to present their VCs to a Verifier. The Verifier can then attest the authorship of the credentials included in the presentation. The data format used for a presentation is [vp-jwt](https://www.w3.org/TR/vc-data-model/#json-web-token). Other formats are not supported at this time. ## Prerequisites * [DID](/svx-v3/guides/api-guides/dids/did-methods) * [Credentials](/svx-v3/guides/api-guides/credentials) ## Who can undertake this operation? Presentations are generated by the Holder and are verified by an Organisation (Verifier), or another user. ## Generate Verifiable Presentation Generate a verifiable presentation, ready for signing. **Endpoint** ```bash POST /presentation/generate ``` **Request** * DID * List of VCs **Response** The presentation object that includes an unsigned JWT. The client calling this endpoint (e.g. Holder wallet) is responsible for adding the signature. ## Verify Verifiable Presentation Verify a given verifiable presentation. The steps performed during verification are: 1. Validate the presentation structure 2. Resolve the presentation DID 3. Verify the presentation signature 4. For each credential in the presentation: * Validate the credential structure * Resolve the Issuer DID * Verify the credential signature **Endpoint** ```bash POST /presentation/verify ``` **Request** * Verifiable Presentation – supported format is vp-jwt **Response** The result of the verification, either true or false. In the event the response is false, all errors are provided, with an explanation. # DIDs The following are step-by-step guides and contextual information relating to DID management via the SVX API. # DID Resolver Resolving & dereferencing supported DID methods ### DID Resolution DID resolution, also referred to as the "Read" operation, is a function that takes a DID (and some metadata) as input and returns a DID document (and some metadata) as output. Resolution is performed as defined in the [DID Core](https://www.w3.org/TR/did-core/) and [DID Resolution](https://w3c-ccg.github.io/did-resolution/) specifications. The implementation is based on the [Universal Resolver](https://github.com/decentralized-identity/universal-resolver) project. Supported output is * DID document and metadata in JSON-LD * DID document in JSON-LD * DID document in CBOR ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw" ``` ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -H "Accept: application/did+ld+json" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw" ``` ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -H "Accept: application/did+cbor" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw" ``` ### DID URL Dereferencing DID URL dereferencing is a function that takes a DID url as input and returns either (1) a DID document, (2) a resource within the DID document or (3) a resource external to the DID document. Using a fragment to fetch ```bash curl -H "Authorization: Bearer b082c420-df67-4b06-899c-b7c51d75fba0" \ -H "Accept: application/did+ld+json" \ -X GET "https://svx-api.meeco.me/did/did:sov:WRfXPg8dantKVubE3HX8pw#key1" ``` # DID Registrar Creating, updating & deactivating supported DID methods DID registration covers the three operations that modify a DID, namely "Create", "Update" and "Deactivate". It takes a DID and (often) a DID document as input to perform the requested operation. Registration is performed as defined in the [DID Core](https://www.w3.org/TR/did-core/) and [DID Registration](https://w3c-ccg.github.io/did-resolution/) (draft) specifications. The implementation is based on the [Universal Registrar](https://github.com/decentralized-identity/universal-registrar) project. # DID Methods Platform supports the following DID Methods
MethodDescriptionSpecificationResolverRegistrar
did:ebsiDIDs on the EBSI network from the European Blockain InitiativeEBSI DID Methodyesyes
did:indyDIDs on Hypledger Indy from Sovrin FoundationIndy DID Methodyesyes
did:keySimples possible implementation of a DID method based on public/private key pairs. Registry independent.Key DID Methodyesyes
did:webDIDs on web server infrastructureWeb DID Methodyesyes
We're working on adding support for the following
MethodDescriptionSpecificationResolverRegistrar
did:hederaDIDs on Hedera Hashgraph from Hbar FoundationHedera DID Methodyesyes
Don't find your preferred DID method in the list? Contact us! # did:key This page describes how to perform the following operations for `did:key` using the SVX platform. * Resolve * Create ### Resolve ```bash curl -H "Authorization: Bearer TOKEN" \ -H 'accept: application/ld+json;profile="https://w3id.org/did-resolution"' \ -X GET "https://svx-api.meeco.me/did/{did:key identifier}" ``` ### Create #### Generate Keypair [Create your DID controller keypair](/svx-v3/guides/api-guides/dids/did-controller-keypair) Encode the public key using Base64 URL encoding. ```bash cat pubkey | tail -c +13 | basenc --base64url # e.g. YeAEwLNEJfHRVMSOs-Fr0C5mW9OFt3GACXtM5A7q7fo= ``` #### Create DID Call DID Create API to create the new DID and return the associated DID document. Use the Base64URL representation of the public key from previous step. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://svx-api.meeco.me/did/create?method=key" \ -H "Content-Type: application/json" \ -d '{ "options": { "clientSecretMode": true }, "secret": { }, "didDocument": { "@context": ["https//www.w3.org/ns/did/v1"], "verificationMethod": [{ "id": "#temp", "type": "JsonWebKey2020", "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "{Replace_With_Above_Generated_Base64URL_String}" } }] } }' # e.g. # { # "jobId": null, # "didState": { # "did": "did:key:z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV", # "state": "finished", # "secret": { # "verificationMethod": [ # [ # { # "id": "#temp", # "purpose": [ # "authentication" # ] # }, # { # "id": "did:key:z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV#z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV", # "controller": "did:key:z6Mkm3KiSaczpWZuLHM19UR3f8cTRk6QPuzagCc2n2XvYRgV", # "purpose": [ # "authentication", # "assertionMethod", # "capabilityInvocation", # "capabilityDelegation", # "keyAgreement" # ] # } # ] # ] # } # }, # "didRegistrationMetadata": { # "duration": 65, # "method": "key" # }, # "didDocumentMetadata": null # } ``` # did:web This page describes how to perform the following operations for `did:web` using the SVX platform. * Resolve * Create * Update * Deactivate ### Resolve ```bash curl -H "Authorization: Bearer TOKEN" \ -H 'accept: application/ld+json;profile="https://w3id.org/did-resolution"' \ -X GET "https://svx-api.meeco.me/did/{did:web identifier}" ``` ### Create #### Generate Keypair [Create your DID controller keypair](/svx-v3/guides/api-guides/dids/did-controller-keypair) Encode the public key using Base64 URL encoding. ```bash cat pubkey | tail -c +13 | base58 # e.g. 7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7 ``` **Create DID** Call the DID Create API to create a new `did:web` and return the associated DID document. Use the Base58 representation of the public key from previous step. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://svx-api.meeco.me/did/create?method=web" \ -H "Content-Type: application/json" \ -d '{ "options": { "clientSecretMode": false }, "didDocument": { "verificationMethod": [ { "id": "did:web:did-web.meeco.me:{Replace_With_Above_Generated_Base58_String}#key-1", "type": "Ed25519VerificationKey2018", "publicKeyBase58": "{Replace_With_Above_Generated_Base58_String}" } ], "service": [ { "type": "LinkedDomains", "serviceEndpoint": "meeco.me" } ], "authentication": [ "did:web:did-web.meeco.me:{Replace_With_Above_Generated_Base58_String}#key-1" ], "assertionMethod": [ "did:web:did-web.meeco.me:{Replace_With_Above_Generated_Base58_String}#key-1" ] } }' # e.g. # { # "jobId": null, # "didState": { # "state": "finished", # "secret": null, # "didDocument": { # "verificationMethod": [ # { # "id": "did:web:did-web.meeco.# me:7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7#key-1", # "type": "Ed25519VerificationKey2018", # "publicKeyBase58": "7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7" # } # ], # "service": [ # { # "type": "LinkedDomains", # "serviceEndpoint": "meeco.me" # } # ], # "authentication": [ # "did:web:did-web.meeco.me:7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7#key-1" # ], # "assertionMethod": [ # "did:web:did-web.meeco.me:7b4frLNZUy5SDnWJTuTCp34TcApYz2kDzBh6wkZudCu7#key-1" # ], # "id": "did:web:did-web.meeco.me:b4c63177-1ba3-48d2-8297-447c843db3d7" # }, # "did": "did:web:did-web.meeco.me:b4c63177-1ba3-48d2-8297-447c843db3d7" # }, # "didRegistrationMetadata": { # "duration": 175, # "method": "web" # }, # "didDocumentMetadata": {} # } ``` ### Update Call the DID Update API to update an existing `did:web` and return the associated DID document. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://identity-network-dev.meeco.me/did/update?method=web" \ -H "Content-Type: application/json" \ -d '{ "did": "{Replace_With_DID_WEB_Identifier}", "didDocumentOperation": [ "setDidDocument" ], "options": { "clientSecretMode": false }, "didDocument": { "id": "{Replace_With_DID_WEB_Identifier}", "verificationMethod": [ { "id": "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1", "type": "Ed25519VerificationKey2018", "publicKeyBase58": "Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE" } ], "service": [ { "type": "LinkedDomains", "serviceEndpoint": "updated.example.com" } ], "authentication": [ "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" ], "assertionMethod": [ "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" ] } }' # e.g. # { # "jobId": null, # "didState": { # "state": "finished", # "didDocument": { # "id": "did:web:did-web.meeco.me:b4c63177-1ba3-48d2-8297-447c843db3d7", # "verificationMethod": [ # { # "id": "did:web:did-web.meeco.# me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1", # "type": "Ed25519VerificationKey2018", # "publicKeyBase58": "Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE" # } # ], # "service": [ # { # "type": "LinkedDomains", # "serviceEndpoint": "updated.example.com" # } # ], # "authentication": [ # "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" # ], # "assertionMethod": [ # "did:web:did-web.meeco.me:Fzn3cccoJqppxiNpPGfwNPaqNHubA3jM798wGzDNwTmE#key-1" # ] # } # }, # "didRegistrationMetadata": { # "duration": 111, # "method": "web" # }, # "didDocumentMetadata": {} # } ``` ### Deactivate Call DID Deactivate API to deactivate an existing `did:web`. ```bash curl -H "Authorization: Bearer TOKEN" \ -X POST "https://identity-network-dev.meeco.me/did/deactivate?method=web" \ -H "Content-Type: application/json" \ -d '{ "did": "{Replace_With_DID_WEB_Identifier}", "options": { "clientSecretMode": false } }' ``` # did:ebsi Working on it. If you need documentation urgently, don't hesitate to reach out to us via the website. # did:indy Working on it. If you need documentation urgently, don't hesitate to reach out to us via the website. # DID Controller Keypair Creating a keypair used to control a DID method Create a new DID controller keypair using openssl. In this example, we use Ed25519, but other algorithms are also supported (see specification). {% hint style="info" %} Make sure you have openssl & GNU coreutils installed and avalible on command line (e.g. `brew install coreutils` on macOS) {% endhint %} ```bash openssl genpkey -algorithm ed25519 -outform DER >privkey openssl pkey -in privkey -pubout -out pubkey -inform DER -outform DER ``` This creates two files, `pubkey` and `privkey`. Depending on the method, the public key is encoded in either * Base64 URL (`base64url`) * Base58 (`base58`) ### FAQ #### How do I install `base58` app (on macOS). There are two ways to install it. If one app doesn't work, try the other one. ```bash # using howbrew brew install base58 # using cargo (requires rust tooling to be installed) cargo install bs58-cli ## hint latter works best by symlinking: ln -s source_path target_in_path/base58 ``` #### How to install & use `openssl 3` (on macOS). Some newer features are only available in the latest version of openssl, version 3. To install it ```bash brew install openssl@3 ``` It is not automatically added to the path as macOS uses LibreSSL. Therefore you can use the absolute path. ``` /opt/homebrew/opt/openssl@3/bin/openssl ``` # OpenID Connect # For Verifiable Presentation Below is a list of endpoints that assist a Holder wallet and a Verifier to participate in the [OpenID for Verifiable Presentations](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html) protocol. Built on top of OAuth 2.0, it allows a client (wallet) to present claims in the form of [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model/). Currently, credentials and presentations in JWT format (vc-jwt, vp-jwt) are supported. The endpoints provided are to support the following high-level verification flow: ```mermaid sequenceDiagram autonumber participant H as End User participant W as Wallet/SIOP participant V as Verifier/RP V->>V: Create Request object V->>V: Generates and displays
QR Code with `request_uri` H-->>W: Opens app W-->>V: Scans QR Code W->>W: Obtains `request_uri`
from QR Code W->>V: Retrieve Request object
(signed JWT) W->>W: Verify Request W->>W: Identify VCs required
in the Request object W->>W: Generates a VP W->>W: Create Response object W->>V: Post Response to /redirect_uri V->>V: Verify Response V-->>W: Acknowledgement ``` The flow centres around the creation and exchange of a Request and a Response object, by the Verifier and Holder (wallet) respectively. The endpoints are categorised under these two headings. ## Prerequisites * [DID](/svx-v3/guides/api-guides/dids/did-methods) * [Presentation](/svx-v3/guides/api-guides/credentials/presentations) ## Who can undertake this operation? Organisations (Verifiers) and users (Holders) in a verification flow using the OpenID Connect protocol. ## Request List of endpoints to help create and verify the [Request](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-request) part of the verification flow. ### Create Presentation Requests Creation of a presentation request. **Endpoint** ```bash POST /oidc/presentations/requests ``` **Request** * Organisation (header, optional) * Name – Title string * Description – Explains the purpose for which the request is created * Verifier * [DID](/svx-v3/guides/api-guides/dids/did-methods) * Name * Expiration Date – Timestamp the request token expires * Redirect Base URI * [Presentation Definition](/svx-v3/guides/api-guides/credentials/presentation-definitions) **Response** The presentation request object that includes an unsigned JWT. The client calling this endpoint (e.g. verifier system) is responsible for adding the signature. ### Update Presentation Request Update an existing presentation request by ID. One of the options is to use the platform to host the (signed) request (see [here](#read-presentation-request-jwt)). The request parameters can't be updated, only the signed request JWT. **Endpoint** ```bash PUT /oidc/presentations/requests/{id} ``` **Request** * Request ID * Organisation (header, optional) * Signed request JWT **Response** The updated presentation request object. ### Read Presentation Request JWT A public endpoint that returns the (signed) presentation request JWT. **Endpoint** ```bash GET /oidc/presentations/requests/{id}/jwt ``` **Request** * Request ID **Response** Signed presentation request JWT token. ### Verify Presentation Request Verification of the SIOP token. The steps performed during this verification are: 1. Resolve Verifier DID 2. Verify request signature 3. Extract the presentation definition URI * Verify presentation definition structure **Endpoint** ```bash POST /oidc/presentations/requests/verify ``` **Request** * Signed presentation request JWT **Responses** The result of the verification, either true or false. ## Response List of endpoints to help create and verify the [Response](https://openid.net/specs/openid-4-verifiable-presentations-1_0.html#name-response) part of the verification flow. ### Create Presentation Response Generate id\_token for request submission based on the wallet information and the verifiable presentation token. **Endpoint** ```bash POST /oidc/presentations/token ``` **Request** * Presentation Request JWT **Response** The presentation response object that includes two unsigned JWTs, `id_token` and `vp_token`. The client calling this endpoint (e.g. Holder wallet) is responsible for adding the signatures for each token. ### Verify Presentation Response Verify the presentation response to a given request. The steps performed are: 1. Verify ID Token 2. Verify VP Token * [Verify presentation](/svx-v3/guides/api-guides/credentials/presentations) 3. Verify if the response is valid for the given request, i.e. if it matches the presentation definition from the request **Endpoint** ```bash POST /oidc/presentations/response/verify ``` **Request** * Presentation Request JWT * Signed ID Token * Signed VP Token **Response** The result of the verification, either true or false. In case of false, all errors are provided, with an explanation. ## Detailed Sequence Diagram of the Flow (API integration) ```mermaid sequenceDiagram title Verify Credentials with API only autonumber participant W as Wallet participant V as Verifier System participant API as SVX API %% %% Terms: %% VP - Verifiable presentation %% VP token - wrapping structure over a verifiable presentation. %% opt RESTful-API call to fetch details of organisation %% Get the DID for the organisation V-->>+API: GET /me MEECO_ORGANISATION_ID={org_id) API-->-V: 200 OK and me object (did_external_id, private_dek_external_id) %% Get the private key associated with DID for the organisation V->>+API: GET /keypairs/{did_external_id} API-->>-V: 200 OK and did signing keypair end %% Create presentation definition opt RESTful-API call to create or retrieve presentation definition V->>+API: POST /presentation_definitions API-->>-V: 200 and presentation definitions created V->>+API: GET /presentation_definitions/{id} API-->>-V: 200 and presentation definitions created end %% Create a presentation request V->>+API: POST /oidc/presentations/request API-->>-V: 201 OK and OIDC request string %% Sign request JWT V->>V: Sign request JWT with did signing keypair %% Update the request V-->>+API: PUT /oidc/presentations/requests/{id} API-->-V: 201 OK and presentation request object
(signed request jwt) V->>W: Show Presentation request as a QR-code or DL W->>W: Scan QR-code, or
open DL W->>API: GET /oidc/presentations/requests/{id}/JWT (public endpoint) API-->>W: 200 OK opt verifiy request signature W->>API: verify OIDC presentation request API-->>W: 200 OK end W->>W: Select credentials %% Build verifiable presentation W->>V: POST /presentations/generate [VC] V-->>W: return unsigned verifiable presentation (VP) W->>W: Sign VP %% Generate id_token for request submission based on the Wallet information and the verifiable presentation token W->>API: POST /oidc/presentations/token API-->>W: 201 OK and unsigned id_token W->>W: Sign id_token %% Submit VP token to the redirect_uri W->>+V: POST "presentation_request.redirect_uri" %% Validate VP token and its content V->>API: POST /oidc/presentations/response/verify API->>API: Verify SIOP token signature and
extract the verifiable presentation API->>API: Verify verifiable presentation structure, signatures and
if data provided match presentation definition API-->>V: 204 OK / 201 OK and parsed token information alt Verify presentation Note right of V: This endpoint will check everything
(signatures, structure, status list information)
and might be an expensive call. V->>API: POST /presentations/verify API-->>V: 204 OK end V-->>W: 201 Submission is valid ``` # Users The following is a step-by-step guide and contextual information relating to user management via the SVX API. # Inviting End-Users The sequence diagram below shows the process of how a user controlling a DID is invited and then added to our system by a tenant administrator. ```mermaid sequenceDiagram title Invite End-User using Wallet to Tenancy autonumber actor H as Holder actor TA as Tenant Admin participant P as Portal participant W as Wallet participant API as SVX API W->>W: did:key generated locally TA->>P: Navigate to Add User > End Users > Manage Tenancy. P->>+API: POST /end-users/invitations API-->>-P: 201 invitation object containing request_uri Note over H,P: There are different ways a holder can receive this link
- QR code that can be scanned
-Deeplink to click on P->>P: Render QR for request
openid://request_uri=https://svx-api-sandbox.meeco.me/oidc/presentations/requests/{id}/jwt TA-->>H: Email QR code / deeplink H->>W: Scan QR Code W->>+API: GET https://svx-api-sandbox.meeco.me/oidc/presentations/requests/{id}/jwt API-->>-W: return request_jwt W->>+W: Extract state and reciret_uri attributes from the request request_jwt W->>+API: POST /end_users/invitations/short_lived_access_token (token: state) API-->>-W: return short lived access_token W->>+API: POST /oidc/presentations/requests/verify (request_jwt, short lived access_token) API-->>-W: 201 OK W->>+API: POST /oidc/presentations/token
(request_id, state, short lived access_token) API-->>-W: 201 OK and unsigned id_token W->>W: Sign id_token W->>+API: POST /end_users/invitations/{token}/accept
(id_token, state: token, short lived access_token)
(endpoint is defined under redirect_uri inside the request_jwt) API-->>-W: 201 OK (access_token: {access_token}) ``` # Authenticating End-Users The sequence diagram below shows the process of how a user controlling a DID, that is registered with a tenant, can authenticate to our system using a [digital wallet](/svx-v3/concepts/digital-wallets). This results in an access token that can be used to communicate with the SVX API. This process is also referred to as DID authentication using SIOP V2. ```mermaid sequenceDiagram title Authenticate End-User to Tenant using Wallet autonumber actor H as Holder participant W as Wallet participant API as SVX API H->>W: Open wallet W->>API: POST /user_authorisation/authentication_requests API-->>W: 201 openid://request_uri={request_uri} W->>API: GET {request_uri} API-->>W: return request_jwt Note over W, API: Wallet uses short lived bearer token to call APIs W->>API: POST /oidc/presentations/requests/verify (request_jwt) API-->>W: 200 OK W->>API: POST /oidc/presentations/token
(request_id, state) API-->>W: 201 OK and unsigned id_token W->>W: Sign id_token W-->>API: POST /user_authorisation/siop_sessions
(id_token, nonce) API-->>W: 201 OK (access_token: {access_token}) ``` # Vault ![Notice stating that this section of Meeco's documentation is undergoing updates.](/files/HC5Bllfau1eCrYV929Is) # Items and Slots This guide describes creating Items and Item Templates using the Meeco API. ## Basic Terms * **Name** — A *machine-readable* non-empty string, for example `phone_number` or `postal_address`. * **Label** — A *human-readable* non-empty string, for example "Phone Number", or "Postal Address". Objects often have both a name and a label with a direct relationship between the two, as suggested by the example. * **Slot** — The smallest data entity in the vault. Each slot has a name, a label, and a value. Values can be strings, dates, or numbers, but also binaries like images or documents. Values are always encrypted. * **Item Template** — A list of empty slots with a label and a name. Each Item is created by cloning such a template and filling in the slots. * **Item** — Contains one or more slots with filled in values. For more information on Vault-specific terminology, see the [Vault overview](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/api-guides/platform/vault/README.md) page. ## Browsing Item Templates Items are created from templates, so we begin by listing all available Item templates: ```bash curl --request GET 'https://sandbox.meeco.me/vault/item_templates' \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" ``` [API docs](https://api-reference-sandbox.svx.exchange/) (Get `API_SUBSCRIPTION_KEY` by [signing up](https://www.meeco.me/signup) for the API, then use the CLI tool to [generate a User and access token](https://github.com/Meeco/js-sdk/tree/master/packages/cli).) The response JSON object lists Templates under the `item_templates` key. Each Template object has a `slot_ids` list, which references Slots in the top-level `slots` list. Here is a truncated sample response: ```json { "item_templates": [ { "id": "ccfaadf6-e040-433f-ad34-904e988a2187", "name": "travel", "description": null, "ordinal": 10, "visible": true, "user_id": null, "updated_at": "2020-01-02T20:32:49.991Z", "template_type": "ItemTemplate", "classification_node_ids": [], "label": "Travel", "background_color": null, "image": "https://api-sandbox.meeco.me/images/7308dc39-d2b1-4039-9960-34f69dd06cd7", "association_ids": [], "associations_to_ids": [], "slot_ids": [ "0cf77509-6eaf-49ff-a036-c3c7e2fee106", "f1668277-0db5-4cff-9210-08a2f245c4aa", "23eea243-1d09-4000-9215-7c1bc534c141", "b57a5d9a-f124-4ddd-954f-18681b2360f1", "929ea8b9-9815-4389-99a9-163f9e0c8b15" ] }, ... ], "slots": [ { "id": "f1668277-0db5-4cff-9210-08a2f245c4aa", "name": "return_date", "description": null, "encrypted": false, "ordinal": 2, "visible": true, "classification_node_ids": [], "slotable_id": "ccfaadf6-e040-433f-ad34-904e988a2187", "slotable_type": "ItemTemplate", "required": false, "updated_at": "2020-01-02T20:32:49.761Z", "created_at": "2020-01-02T20:32:49.761Z", "config": null, "slot_type_name": "date", "creator": "system", "binary_ids": [], "label": "Return date", "image": null, "encrypted_value": null }, ... ], "shares": [], "classification_nodes": [ ... ], "associations": [], "associations_to": [], "attachments": [], "thumbnails": [], "meta": { "pages": null, "total_count": null } } ``` Here's a sample of Item Templates you might get: * `passport_details` * `password` * `important_document` * `vehicle` * `travel` * `bank_item` * `membership_subscription` * `pet` * `device` * `important_document` * `custom` * `services` ### Finding a Specific Template You can get a specific Template using its `id` (replace `ITEM-TEMPLATE-ID`): ```bash curl --request GET 'https://sandbox.meeco.me/vault/item_templates/ITEM-TEMPLATE-ID' \ -H 'Authorization: Bearer $VAULT_ACCESS_TOKEN' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' ``` [API docs](https://api-reference-sandbox.svx.exchange/) Or, to search Item Templates by matching `label` text (replace `SEARCH_TEXT`): ```bash curl --request GET 'https://sandbox.meeco.me/vault/item_templates?like=SEARCH_TEXT' \ -H 'Authorization: Bearer $VAULT_ACCESS_TOKEN' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' ``` [API docs](https://api-reference-sandbox.svx.exchange/) ## Creating an Item The example below creates an Item from the `vehicle` Template. Using the CLI, we can see that the `vehicle` Template has the following Slots: * `model_make` * `licence_plate` * `vin` * `type` * `purchase_date` For now the new Item's Slots are left empty. A [later section](#encryption-of-user-data) will cover encrypting data and adding it to a created Item. To create an Item you must give the name of an existing Item Template, and a label: ```bash curl --request POST 'https://sandbox.meeco.me/vault/items' \ -H 'Authorization: Bearer $VAULT_ACCESS_TOKEN' \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ --data \ '{ "template_name": "vehicle", "item": { "label": "My Car" } }' ``` [API docs](https://api-reference-sandbox.svx.exchange/) The API response is the newly created Item: ```json { "item": { "id": "e053853d-6a7e-476b-8e3b-d78b4e6d2802", "name": "vehicle", "label": "Vehicle", "description": null, "created_at": "2020-03-12T04:38:24.110Z", "item_template_id": "61516c6f-81df-4c86-96df-8af915f0aec0", "ordinal": 1, "visible": true, "updated_at": "2020-03-12T04:38:24.556Z", "item_template_label": "Vehicle", "shareable": false, ... "association_ids": [], "associations_to_ids": [], "slot_ids": [ "f84d82be-7d82-4ccb-b7ae-e30be5b036c9", "6e1e4ecc-0b8b-45c1-919f-01e69f05bbf8", "f09975cc-ec8e-4744-b883-73c115d32434", "32d1f51b-d26e-4c85-8589-133a4f8e4579", "5addd943-948d-4f80-b1e8-771ff5fee2c1", "1fdd1473-a178-43dc-8862-c1aa242cf861", "e4d7f7ed-de2c-4819-9369-478f2357b6aa", "4cd09df4-9b69-4579-9e76-9a6d7c314b02" ] }, "classification_nodes": [], "shares": [], "connections": [], "attachments": [], "thumbnails": [], "slots": [ { "id": "f84d82be-7d82-4ccb-b7ae-e30be5b036c9", "name": "image", "description": null, "encrypted": false, "ordinal": 6, "visible": true, "classification_node_ids": [], "slotable_id": "e053853d-6a7e-476b-8e3b-d78b4e6d2802", "slotable_type": "Item", "required": false, "updated_at": "2020-03-12T04:38:24.531Z", "created_at": "2020-03-12T04:38:24.531Z", "config": null, "slot_type_name": "image", "creator": "system", "binary_ids": [], "label": "Image", "image": null, "encrypted_value": null }, ... ], "associations": [], "associations_to": [] } ``` Notice that Slots are created according to the Item Template, but are left empty for now. Items can also be classified, that is described in [another page](/svx-v3/guides/api-guides/vault/classification-hierarchies). ### Item Names An Item's `name` is auto-generated from its label. Names are all lower-case, have no non-alphanumeric characters, and have whitespace replaced with underscores. For example, label `A strange &8Label` would become `a_strange_8label`. Any user specified names (for Slots and Items) are sanitized to this format. Item names and labels do not have to be unique, unlike Item Template names. ### Extra Slots The Slots in the Item Template are present in every Item created from that Template, but Items can have additional Slots too. Any extra Slots described in `slots_attributes` are created for the new Item. For example, if `my_template` had Slots `foo` and `bar`, and we create an Item with ```json { "template_name": "my_template", "item": { "label": "A Test Item", "slots_attributes": [ { "label": "baz", "slot_type_name": "key_value" } ] } } ``` Then the new Item will have Slots `foo`, `bar` and `baz`. The next section has more information about creating Slots. ## Creating a Custom Template It is possible to create a Custom Template which we can use to create our own Items. Only the `label` property is required, it will auto-generate a `name` (as described above). Since Item Templates are referenced by their name, the generated name must be unique. You can specify it separately if the label does not generate a unique name. ```bash curl --request POST "https://sandbox.meeco.me/vault/item_templates" \ -H "Content-Type: application/json" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ -H "authorization: Bearer $VAULT_ACCESS_TOKEN" \ --data \ '{ "name": "example_custom_template", "label": "Example Custom Template", "description": "An example template", "slots_attributes": [ { "label": "An Example Slot", "slot_type_name": "key_value" } ] }' ``` The new Template will look like this: ```json { "item_template": { "id": "66c6b284-434e-4411-9435-7bd70a74c6d2", "name": "example_custom_template", "description": "An example template", "ordinal": 0, "visible": true, "user_id": "68a2cdb3-4a9d-42ac-83e7-d7e4967143a0", "updated_at": "2020-09-28T02:03:11.348Z", "label": "Example Custom Template", "slot_ids": [ "e019d2a6-36ed-4768-9aec-273879273d23" ], "classification_node_ids": [], "background_color": null, "image": null }, "slots": [ { "id": "e019d2a6-36ed-4768-9aec-273879273d23", "name": "an_example_slot", "description": null, "encrypted": false, "ordinal": 0, "visible": true, "classification_node_ids": [], "item_id": null, "required": false, "updated_at": "2020-09-28T02:03:11.424Z", "created_at": "2020-09-28T02:03:11.376Z", "config": null, "slot_type_name": "key_value", "creator": null, "label": "An Example Slot", "image": null, "attachment_id": null, "own": false, "share_id": null, "original_id": null, "owner_id": null, "encrypted_value": null, "encrypted_value_verification_key": null, "value_verification_hash": null } ], "classification_nodes": [], "attachments": [], "thumbnails": [] } ``` Then, you can create an item from your new template: ```bash curl --request POST "https://sandbox.meeco.me/vault/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "An example item with custom template", "slots_attributes": [] }, "template_name": "example_custom_template" }' ``` The created item comes back looking like the following, with a custom slot that was part of the template creation call. ```json { "item": { "id": "98db3af3-c430-45ce-a5eb-cce89b19f736", "name": "an_example_item_with_custom_template", "label": "An example item with custom template", "description": "An example template", "created_at": "2020-09-28T02:12:56.194Z", "item_template_id": "66c6b284-434e-4411-9435-7bd70a74c6d2", "ordinal": 1, "visible": true, "updated_at": "2020-09-28T02:12:56.271Z", "item_template_label": "Example Custom Template", "item_image": null, "item_image_background_colour": null, "slot_image": null, "slot_image_background_colour": null, "category_image": null, "category_image_background_colour": null, "category_label": null, "original_id": null, "owner_id": "68a2cdb3-4a9d-42ac-83e7-d7e4967143a0", "share_id": null, "image": null, "image_background_colour": null, "me": false, "background_color": null, "classification_node_ids": [], "association_ids": [], "associations_to_ids": [], "slot_ids": [ "445ee1d0-0100-458d-9f7a-4698b6aaf1f0" ], "own": true }, "associations": [], "associations_to": [], "classification_nodes": [], "slots": [ { "id": "445ee1d0-0100-458d-9f7a-4698b6aaf1f0", "name": "an_example_slot", "description": null, "encrypted": false, "ordinal": 0, "visible": true, "classification_node_ids": [], "item_id": "98db3af3-c430-45ce-a5eb-cce89b19f736", "required": false, "updated_at": "2020-09-28T02:12:56.247Z", "created_at": "2020-09-28T02:12:56.247Z", "config": null, "slot_type_name": "key_value", "creator": "user", "label": "An Example Slot", "image": null, "attachment_id": null, "own": true, "share_id": null, "original_id": null, "owner_id": "68a2cdb3-4a9d-42ac-83e7-d7e4967143a0", "encrypted_value": null, "encrypted_value_verification_key": null, "value_verification_hash": null } ], "attachments": [], "thumbnails": [] } ``` Notice that the Item's `description` property inherits the `description` of the Item Template. There are a few limitations on the use of Item Templates: * There currently isn't a way to share custom templates with other users. * Templates cannot be changed or deleted ### Slots Slots represent a key-value pair, where the value is always encrypted. The Meeco Vault will check and reject any `encrypted_value` data that doesn't match the cryppo serialization format. Slots are always owned by an Item (or an Item Template, but these Slots are never read), and news Slots are created for each new Item. Their most important properties are: | Property | Description | | ----------------- | --------------------------- | | `name` | Machine-readable string | | `label` | Display name | | `description` | Longer name | | `encrypted_value` | Output of Cryppo encryption | | `slot_type_name` | string | The `slot_type_name` property must be one of * `key_value` * `bool` * `classification_node` * `color` * `date` * `datetime` * `image` * `note_text` * `select` * `attachment` * `url` * `phone_number` * `select_multiple` * `email` * `password` As the Vault cannot inspect the data, it is just a suggestion to the user. Type `key_value` is the default. Slots are created either by cloning an Item Template, or via the `slots_attributes` property when creating an Item. Since they are keyed by `name`, either `label` or `name` must be non-empty on creation. Slots are updated by calling `PUT /vault/items` with the new data in `slots_attributes`: ```bash curl --request PUT "https://sandbox.meeco.me/vault/items/bef961af-aa1f-4f1c-ac95-cdb41b3682db" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "slots_attributes": [ { "name": "bar", "label": "A new label" } ] } }' ``` As Slots are keyed by their names, names should be unique per Item. Slots can also be deleted by calling `DELETE /slot/id`. This deletes the Slot (and it's data) from the parent Item. Slots in Item Templates cannot be deleted. ## Encryption of User Data One of the core features of the Meeco platform is data encryption. User data stored in the Meeco Vault is encrypted in such a way that no one - including Meeco - can decrypt and read it other than the user. If we want to store data in an Item we must encrypt it, otherwise the Vault will return an error. To get familiar with the kinds of cryptographic key the Meeco platform uses please follow either the [Onboarding to SVX](/svx-v3/guides/onboarding-to-svx) guide, or "[Setting Up Access to the Vault and Keystore](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/api-guides/vault/setting-up-access.md)". That will introduce you to the Cryppo library that we use to make encryption, decryption and serialization simpler in the context of the Meeco Service. In the following example, we will use the Data Encryption Key (DEK) that the CLI generated for us from the Quickstart guide (and saved into the \`.user.yaml\` file) to encrypt a Slot value. In the real world this process would involve a few more steps: * Reading the encrypted Key Encryption Key (KEK) from the Key Store * Decrypting it with the Password Derived Key (PDK) * Reading a DEK from the Key Store * Decrypting it with the KEK If you do not have a DEK already, you can also generate one using the \`cryppo-cli\` and the following command: ```bash cryppo genkey ``` Result: ```bash URL-Safe Base64 encoded key: 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg= ``` To encrypt slot value \`BMW\` run the following command: ```bash cryppo encrypt -v BMW -k 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg= ``` Result: ```bash Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo= ``` The output above is the encrypted slot value ready to be stored in the Vault. We can decrypt by running the following command: ```bash cryppo decrypt -s Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo= -k 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg= BMW ``` The Meeco platform uses the serialization format of Cryppo. If no derived key is used, each such string contains three parts concatenated with a dot: * Encryption strategy name * Encoded encrypted data encoded with Base64 * Encoded encryption artefacts serialized into a hash converted to YAML, then encoded with Base64 If you are feeling adventurous you are welcome to dig into the [Cryppo-CLI](https://github.com/Meeco/cryppo-cli) The example below creates an Item config file. We need to provide a template name to create an item config file. ```bash meeco items:create-config TEMPLATENAME > .item_config.yaml ``` This command will create the config file for the item to be created in the next step. The TEMPLATENAME can be any template from the list above. The Meeco CLI can then create the item by the following command: ```bash meeco items:create .item_config.yaml ``` will create the Item encrypting the Slots described in `.item_config.yaml` using the current user's keys. You can also integrate this flow into your app using the Meeco SDK's `UserService`. ### Filling Slot Values Thanks to the Item Template our new Item already has a list of empty Slots, and a list of classification tags. Let's fill in a value of the \`encryptedvalue\` slot using the encrypted value from the previous step: ```bash curl --request PUT \ 'https://sandbox.meeco.me/vault/items/049740cb-ad1f-43d9-9254-ae25eba30f47' \ -H 'Authorization: $VAULT_ACCESS_TOKEN' \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ -d ' { "item": { "label": "vehicle", "slots_attributes": [ { "label": "Make or model", "encrypted_value": "Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo=", "slot_type_name": "key_value", "name": "model_make" } ] } } ' ``` Response: ```json { "item": { ... }, ... "slots" [ ... { "id": "ce9d89f8-a50a-486a-b007-d1cb006ee157", "name": "model_make", "description": null, "encrypted": true, "ordinal": 1, "visible": true, "classification_node_ids": [], "slotable_id": "049740cb-ad1f-43d9-9254-ae25eba30f47", "slotable_type": "Item", "required": false, "updated_at": "2020-03-18T06:49:31.160Z", "created_at": "2020-03-18T06:49:17.549Z", "config": null, "slot_type_name": "key_value", "creator": "system", "binary_ids": [], "label": "Make or model", "image": null, "encrypted_value": "Aes256Gcm.MtK4.LS0tCml2OiAhYmluYXJ5IHwtCiAgdXN4NnozRnRUc2FldlBmdgphdDogIWJpbmFyeSB8LQogIHc2YmRTM252Z2o4TTZYSE9FUnhHd1E9PQphZDogbm9uZQo=" }, ], } ``` ## Shared Items The page on [Connections and Sharing](/svx-v3/guides/api-guides/vault/connections-and-sharing) covers sharing Items. This section will just describe some properties of shared Items. ### Receiving A Share You receive a shared item by calling `PUT https://sandbox.meeco.me/vault/incoming_shares/{share_id}/accept`. (This indicates you accept the share terms, if any). Next call `GET https://sandbox.meeco.me/vault/incoming_shares/{share_id}/item` and view the Item that has been created in your Vault. Note that `share.item_id` is the original Item's id, not the one in your Vault! ### Owners An Item's owner is its original creator. The following table summarizes the how properties of an Item change when you are the owner, vs the receiver of a shared copy. | Property | Owner Vaule | Receiver Value | | ------------- | ----------- | --------------- | | `own` | true | false | | `original_id` | null | `share.item_id` | | `share_id` | null | `share.id` | As a result, if `item.share_id` is non-null, then it is a share you received, and you can view the share via `GET https://sandbox.meeco.me/vault/incoming_shares/{item.share_id}`. Owners have the ability to push updates of shared data, and can share the Item with anyone. Receivers of a shared Item can only share that Item if `item.sharing_mode` is `anyone`. # Connections and Sharing How to create a connection between you and another user to share data ### A follow along guide using the Meeco CLI to build on the Quickstart Guide *Below the guide using the CLI we have a more in depth explanation of how sharing works* After successfully creating an item in your user's Vault from the [Onboarding to SVX](/svx-v3/guides/onboarding-to-svx), it's now time to create another user called Bob. ```bash meeco users:create -p supersecretpassword > .bob.yaml ``` We used the same password as in the [Onboarding to SVX](/svx-v3/guides/onboarding-to-svx) example, in case you were wondering. Using the CLI again, we're going to make a connection configuration file between *Alice* and *Bob* ```bash meeco connections:create-config --from .alice.yaml --to .bob.yaml > .connection_config.yaml ``` This creates a file called `.connection_config.yaml` which we will open and edit the `fromName` and `toName` keys. Let's make it between Alice and Bob. Next, it's time to use the CLI again to create the connection between the two users. ```bash meeco connections:create -c .connection_config.yaml > .connection.yaml ``` This generates the keypairs for the connection, creates and accepts the invitation for the two users. Now, we're ready to select an item from Alice's vault and share it with Bob. First, we'll need to create the share template with the CLI. ```bash meeco shares:create-config --from .alice.yaml -c .connection.yaml -i .item.yaml > .share_config.yaml ``` After this configuration file is created, we can create the share between the two users: ```bash meeco shares:create -c .share_config.yaml > .share.yaml ``` The output is a new shares item: ```bash shares: - id: 0f894916-852a-4682-bd49-0783ab58e1c0 owner_id: ab9f9fce-db0b-4384-a221-617efa80dba7 sender_id: ab9f9fce-db0b-4384-a221-617efa80dba7 recipient_id: ce021e77-a66f-4fae-a150-d3a4a6e1a7f9 acceptance_required: acceptance_not_required item_id: bae62ab6-ea95-4037-8f6c-3708c81b2d77 slot_id: null public_key: "-----BEGIN PUBLIC KEY-----\r ... -----END PUBLIC KEY-----\r\n" ... sharing_mode: owner keypair_external_id: f0ab31a1-c95d-463d-b6b1-1a72e1f56444 encrypted_dek: Rsa4096.Jm9R1Ve2KcOLc4-HkZkjviB8HXBSlVQLfTlUJ-xcGRRklBp-Od-g2YjareSFwMorzVrtVDKWg8QWkB3iDAn_g9pG3c-kY1Le5Gb86VTO3hhx74jImf_iw29VUUcAsfRQH2u69X5byyYYlg827nMpT8CgN4P3USsMsMMsXrppu7ONGwk-xxItJtr8S3cONECp5L_4cbcR4IDbGBpVGZMdU5X6YU3ZZ7z-fi5wF5tRp6krR4V8rqbJOlyURY2xwj3ihoGtPc6Dbef_H6viFEgl00gyDegXKgJ8IisES_6_cyq7ooiGbux5oTgyg4tTIA40Lf65JLzVujosFC56EatRumR-YretG_Dkr61PQfuGN2zpTOGpZzypnc-HJc-GCHWGLU1wqwhcBY3NNoM1NvmdWGRQV2Vrtt3rhBCM2Nt-E7lCyQTX45qGXG-q-nL2b6l_DfCfp6O5s4hAYVoBQgDLCexl1YFb0reNm1Ol3rQ_hjpPn9LHAgE93Mdq7b04-sBmbNF54oLyrAneZu8NOle1-dioK13dLNooSm_O5MuRdnjyaJZH5zcsN-mEeSzsTHBymiMitet1-YOoZrenLDUaaFpWj6fCgwW6louU7u8PWq8U40TV15c8TndQAVFyRhfPav8HHLhOJmOCa1HaqdGZ8vuw1efJW3rtOU2ye31JQIw=.QQUAAAAA terms: null created_at: 2020-09-24T07:15:03.315Z expires_at: null ``` The CLI sets up a *private encryption space* between Alice and Bob and then shares the item. We never created an item for the Bob, so we know that the following command will show the item that has been shared with Bob. ```bash meeco shares:get-incoming -a .bob.yaml ``` The following is the share information, as well as the item that was shared: ```bash share: id: 0f894916-852a-4682-bd49-0783ab58e1c0 owner_id: ab9f9fce-db0b-4384-a221-617efa80dba7 sender_id: ab9f9fce-db0b-4384-a221-617efa80dba7 recipient_id: ce021e77-a66f-4fae-a150-d3a4a6e1a7f9 acceptance_required: acceptance_not_required item_id: bae62ab6-ea95-4037-8f6c-3708c81b2d77 slot_id: null ... sharing_mode: owner keypair_external_id: f0ab31a1-c95d-463d-b6b1-1a72e1f56444 encrypted_dek: Rsa4096.Jm9R1Ve2KcOLc4-HkZkjviB8HXBSlVQLfTlUJ-xcGRRklBp-Od-g2YjareSFwMorzVrtVDKWg8QWkB3iDAn_g9pG3c-kY1Le5Gb86VTO3hhx74jImf_iw29VUUcAsfRQH2u69X5byyYYlg827nMpT8CgN4P3USsMsMMsXrppu7ONGwk-xxItJtr8S3cONECp5L_4cbcR4IDbGBpVGZMdU5X6YU3ZZ7z-fi5wF5tRp6krR4V8rqbJOlyURY2xwj3ihoGtPc6Dbef_H6viFEgl00gyDegXKgJ8IisES_6_cyq7ooiGbux5oTgyg4tTIA40Lf65JLzVujosFC56EatRumR-YretG_Dkr61PQfuGN2zpTOGpZzypnc-HJc-GCHWGLU1wqwhcBY3NNoM1NvmdWGRQV2Vrtt3rhBCM2Nt-E7lCyQTX45qGXG-q-nL2b6l_DfCfp6O5s4hAYVoBQgDLCexl1YFb0reNm1Ol3rQ_hjpPn9LHAgE93Mdq7b04-sBmbNF54oLyrAneZu8NOle1-dioK13dLNooSm_O5MuRdnjyaJZH5zcsN-mEeSzsTHBymiMitet1-YOoZrenLDUaaFpWj6fCgwW6louU7u8PWq8U40TV15c8TndQAVFyRhfPav8HHLhOJmOCa1HaqdGZ8vuw1efJW3rtOU2ye31JQIw=.QQUAAAAA terms: null created_at: 2020-09-24T07:15:03.315Z expires_at: null associations_to: [] associations: [] attachments: [] classification_nodes: - id: 8670d4c6-8d68-49a4-bd21-0fc8cefa705d name: vehicle label: Vehicle description: null ordinal: 3 background_color: null image: https://sandbox.meeco.me/vault/images/ff1c25e9-530a-4103-b649-986631bcAAAAA scheme: meeco item: id: a3f632c8-f80f-47aa-9e26-aab15ad9ed63 own: false name: a_new_item label: A New Item description: null created_at: 2020-09-24T07:15:03.452Z item_template_id: 0c385f1d-8825-4932-a6ab-846178b816e4 ordinal: 0 visible: true updated_at: 2020-09-24T07:15:03.493Z ... ``` Running `meeco shares:list -a .bob.yaml` will show all the shares information that Bob has received, even from other users. `meeco shares:list -t outgoing -a .alice.yaml` will show all the shares that are outgoing from Alice to other users. If you're looking for a way to delete the share, you can do that as either user with `meeco shares:delete -a .alice.yaml ` or `meeco shares:delete -a .bob.yaml ` Well done - you've now created a connection between two users, and shared an item! ## Sharing Items Between Users - In Depth All user data stored in the Vault is encrypted and can only be decrypted and read by the user. However, the Meeco platform makes it possible for one user to share items with another user. We will cover this process and its steps in this guide. In summary, the sharer will generate a DEK (data encryption key) specifically for the purpose of this share and re-encrypt the shared item with this key. In order to share the DEK, Public Key cryptography is used: the sharer will encrypt the DEK with a Public Key of the share recipient, so only the share recipient can decrypt the DEK with their Private Key, and then use the DEK to decrypt the item. ![](/files/6Q03a71XeVabWuq16FAF) Let's dive into it. ### Invitation To Connect Before anything can be shared, 2 Users need to establish a ***connection***. In order to create a connection in this example, User 1 (Alice) will invite User 2 (Bob) The process can be described in the following sequence diagram: ![](/files/5tQho7Pn3WzsMeWrY0nB) At step (1) User 1 generates a Keypair which will be used for inviting another user, and later for the key exchange. Steps 2-4 are part of the standard procedure used for storing Keypairs in the Keystore. If there is a Keypair, it is encrypted by the Key Encryption Key (KEK) and stored in the Keystore. Please read guide [Setting Up Access to the Vault and Keystore](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/api-guides/vault/setting-up-access.md) if you haven't read it yet. In steps 5 and 6, stores the Public Key. In steps 5-7 User 1 creates an invitation using the following as input: * email of the user that User 1 wants to connect to (User 2) * the Public Key After step 7 the Vault sends an invitation email to User 2. ### Accepting Invitation In this section we'll describe the scenario when User 2 accepts the invitation from User 1. This process can be described in the following sequence diagram: ![](/files/qC7J9589dd7vAO1SMY7l) Most of these steps are the the same steps of User 1 in the previous section: just like User 1, User 2 generates a Keypair for this connection (step 9), encrypts it and stores in the Keystore (steps 10-12), and publishes the Public Key in the Vault (steps 13-14). The most important step is a call to create a connection as step 13. The parameters of the call are the invitation ID and the invitation token. The most important results after these two sections are as follows: * The connection between User 1 and User 2 has now been established * User 1 has access to the Public Key of User 2 on the connection record * User 2 has access to the Public Key of User 1 on the connection record ### Creating A Share In this section, to create a share, User 1 will generate a DEK dedicated to this share, re-encrypt a item and store it as a share, and share the DEK with User2, encrypted by the Public Key of User 2. Creation of a share can be described in the following sequence diagram: ![](/files/9k0wD63S5bu9Yy73SLfB) At step 19 User 1 generates a DEK. This DEK will be used to encrypt the shared item. We also need to have the key readable by User 2, so at step 20 we encrypt the same DEK with the Public Key of User 2. In steps 21-23 User 1 encrypts the item data with the shared DEK and creates a Share record. The main results of these steps are as follows: * A DEK has been created and encrypted with User 2's public key * A Share record has been created in the Vault with the encrypted DEK, and it is linked to the connection between User 1 and User 2 ### Reading The Share Reading of the share can be described in the following sequence diagram: ![](/files/EWwIF7SOxUzHhtFLxXZX) First in step 24 User 2 retrieves a list of all items both his own and shared incoming. If there is a new share User 2 needs to decrypt and read, in step 26 User 2 requests the share details. User 2 also retrieves the DEK in steps 26-27, decrypts it with their Private Key in step 28 and decrypts the share in step 29. # Classification Hierarchies In the Meeco Vault, Items, Item Templates and Slots can be tagged with **Classification Nodes**. If an Item has been tagged with a Classification Node, you can find it again by searching for that Classification Node. Classification Nodes are a lot like tags, but are grouped into Schemes. Schemes might represent similar topics, or classifications from an existing app. A Classification Node is structured like | Property | Type | Description | | ----------- | ------ | ------------------------------------------- | | name | string | Machine-readable name | | label | string | Human-readable name | | description | string | Explains what the classification represents | | scheme | string | See [Schemes](#schemes) | ## Browsing Classification Nodes The `$VAULT_ACCESS_TOKEN` can be grabbed from the user file you created in the [Onboarding to SVX](https://github.com/Meeco/docs/blob/archive/svx-3.x/guides/api-guides/vault/guides/onboarding-to-svx.md) guide. All classification nodes can be queried by `GET /vault/classification_nodes`: ```bash curl --request GET \ 'https://sandbox.meeco.me/vault/classification_nodes' \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" ``` [API Docs](https://api-reference-sandbox.svx.exchange/) You can modify the request with the following query parameters: * `scheme_name`, see below * `by_name` - a "LIKE" search which will return results for partial matches - i.e. 'fin' will return 'financial' ## Schemes Classification Nodes are grouped by Schemes. Available Schemes are set by the Vault and cannot be changed. These are the existing schemes: * `tag` * `country` * `meeco_wallet` * `region` You must use `tag` as the default scheme. ## Creating a Classification Node You can create a Classification node as follows ```bash curl --request POST 'https://sandbox.meeco.me/vault/classification_nodes' \ -H "authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ --data \ '{ "classification_node": { "classification_scheme_name": "tag", "name": "my-new-tag", "label": "My Tag", "description": "Hi There this is my Tag!" } }' ``` [API Docs](https://api-reference-sandbox.svx.exchange/) ```json { "classification_node": { "id": "b4ff857f-6f50-4608-bd93-b61a7dd012d5", "background_color": null, "description": "Hi There this is my Tag!", "image": null, "label": "My Tag", "name": "my-new-tag", "ordinal": 0, "scheme": "tag" } } ``` Properties `classification_scheme_name` and either `name` or `label` are mandatory. As mentioned above, `classification_scheme_name` should usually be 'tag'. As for other Vault objects, if only `label` is given, then the name is created by translating the label text. Since `name` is used to link a Classification Node to a Vault object, it must be unique. Note that currently, as for Item Templates, the API does not allow: * updating Classification Nodes, * deleting Classification Nodes, * sharing new Classification Nodes ## Applying Classifications Classification Nodes can be applied to Item Templates, Items and Slots. Most provide a way of creating new Classification Nodes in the same request. ### Templates Single Classification Nodes may be applied to Item Templates: ```bash curl --request POST 'https://sandbox.meeco.me/item_templates' \ -H "authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H 'content-type: application/json' \ -H 'Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY' \ --data \ '{ "label": "Some Template", "classification_scheme_name": "tag", "classification_node_name": "new_node", "slots_attributes": [] }' ``` Note that both `classification_scheme_name` and `classification_node_name` are required, and both must exist. Result ```json { "item_template": { "id": "78724525-9aed-4156-90c5-447198aa818b", "name": "some_template", "description": null, "ordinal": 0, "visible": true, "user_id": "e414dc7a-b6f1-4fb6-9481-41d7be5c8785", "updated_at": "2020-10-07T04:13:01.305Z", "label": "Some Template", "slot_ids": [], "classification_node_ids": [ "15ab7625-11f5-4518-99eb-e985c24414ad" ], "background_color": null, "image": null }, "slots": [], "classification_nodes": [ { "id": "15ab7625-11f5-4518-99eb-e985c24414ad", "background_color": null, "description": null, "image": null, "label": "New Tag", "name": "new_tag", "ordinal": 0, "scheme": "tag" } ], "attachments": [], "thumbnails": [] } ``` This has two effects. First, the Item Template can be found via its Classification Node or Scheme name, e.g. queries `GET /vault/item_templates?by_classification=tag`, or `GET /vault/item_templates?by_classification=new_tag` should include the template. Second, new Items created with the Item Template will be classified with the Classification Node. ```bash curl --request POST "https://sandbox.meeco.me/vault/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "Fun example", "slots_attributes": [ { "name": "bar" } ] }, "template_name": "some_template" }' ``` ```json { "item": { "id": "658ca227-b61b-4ce0-846d-baaf4cc17880", "name": "fun_example", "label": "Fun example", "description": null, "created_at": "2020-10-07T04:13:52.430Z", "item_template_id": "78724525-9aed-4156-90c5-447198aa818b", "classification_node_ids": [ "15ab7625-11f5-4518-99eb-e985c24414ad" ], "association_ids": [], "associations_to_ids": [], "slot_ids": [ "932e1f7e-10b5-4658-95b8-d5dff164bf37" ], "own": true, "...": "..." }, "associations": [], "associations_to": [], "classification_nodes": [ { "id": "15ab7625-11f5-4518-99eb-e985c24414ad", "background_color": null, "description": null, "image": null, "label": "New Tag", "name": "new_tag", "ordinal": 0, "scheme": "tag" } ], "slots": [ { "id": "932e1f7e-10b5-4658-95b8-d5dff164bf37", "name": "bar", "classification_node_ids": [], "item_id": "658ca227-b61b-4ce0-846d-baaf4cc17880", "...": "..." } ], "attachments": [], "thumbnails": [] } ``` ### Items Classification nodes are added to Items by passing `classification_nodes_attributes`, just like adding Slots. If the name and scheme match an existing Classification Node, it is used, otherwise a new one is created. Classification Node can be applied to both the Item and the Slots it contains. Unlike Item Templates, Items may have multiple classifications. ```bash curl --request POST "https://sandbox.meeco.me/vault/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "item class", "classification_nodes_attributes": [ { "name": "my_new_tag", "scheme": "tag" } ], "slots_attributes": [] }, "template_name": "some_template" }' ``` ```json { "item": { "id": "ff04474c-f661-4f71-b5a3-c40452c30e3b", "name": "item_class", "label": "item class", "description": null, "created_at": "2020-10-07T04:55:54.953Z", "item_template_id": "01bbb6a4-7466-423f-afdb-2d2f314011c4", "ordinal": 1, "visible": true, "updated_at": "2020-10-07T04:55:54.987Z", "item_template_label": "Some Template", "owner_id": "e414dc7a-b6f1-4fb6-9481-41d7be5c8785", "share_id": null, "classification_node_ids": [ "a9b7b318-2e22-4969-a521-e6d43d882bf6" ], "association_ids": [], "associations_to_ids": [], "slot_ids": [], "own": true, "...": "..." }, "associations": [], "associations_to": [], "classification_nodes": [ { "id": "a9b7b318-2e22-4969-a521-e6d43d882bf6", "background_color": null, "description": "Hi There this is my Tag!", "image": null, "label": "My New Tag", "name": "my_new_tag", "ordinal": 0, "scheme": "tag" } ], "slots": [], "attachments": [], "thumbnails": [] } ``` Note that even if the Classification Node `name` property matches an existing Node, but other fields don't, then a new Classification Node will be created. The `scheme` property must match an existing Scheme. Classification Nodes can be added to Slots too: ```bash curl --request POST "https://sandbox.meeco.me/items" \ -H "content-type: application/json" \ -H "Authorization: Bearer $VAULT_ACCESS_TOKEN" \ -H "Meeco-Subscription-Key: $API_SUBSCRIPTION_KEY" \ --data \ '{ "item": { "label": "Another Item", "slots_attributes": [ { "name": "new_slot", "description": "Some Slot", "slot_type_name": "key_value", "label": "New Slot", "classification_nodes_attributes": [ { "label": "A New Tag", "description": "Tag For The Slot", "scheme": "tag" }, { "name": "my_new_tag", "scheme": "tag" } ] } ] }, "template_name": "some_template" }' ``` In this case the `new_slot` receives both an existing Classification Node and a new one. ```json { "item": { "id": "bfa4c439-fc34-41e6-aba2-12191061ccb2", "name": "another_item", "label": "Another Item", "description": null, "created_at": "2020-10-07T05:15:42.039Z", "item_template_id": "01bbb6a4-7466-423f-afdb-2d2f314011c4", "ordinal": 1, "updated_at": "2020-10-07T05:15:42.131Z", "item_template_label": "Some Template", "owner_id": "e414dc7a-b6f1-4fb6-9481-41d7be5c8785", "classification_node_ids": [], "association_ids": [], "associations_to_ids": [], "slot_ids": [ "636faed0-11f2-4cc4-876e-9ce1118381c8" ], "own": true, "...": "..." }, "associations": [], "associations_to": [], "classification_nodes": [ { "id": "ec6a92a2-5578-49cf-b7de-23f7a7cf8081", "background_color": null, "description": "Tag For The Slot", "image": null, "label": "A New Tag", "name": "a_new_tag", "ordinal": 0, "scheme": "tag" }, { "id": "8ca80da9-53fa-4762-9b3b-857153f2dea0", "background_color": null, "description": null, "image": null, "label": "My new tag", "name": "my_new_tag", "ordinal": 0, "scheme": "tag" } ], "slots": [ { "id": "636faed0-11f2-4cc4-876e-9ce1118381c8", "name": "new_slot", "description": "Some Slot", "classification_node_ids": [ "ec6a92a2-5578-49cf-b7de-23f7a7cf8081", "8ca80da9-53fa-4762-9b3b-857153f2dea0" ], "item_id": "bfa4c439-fc34-41e6-aba2-12191061ccb2", "slot_type_name": "key_value", "label": "New Slot", "...": "..." } ], "attachments": [], "thumbnails": [] } ``` ### Slots Slots are usually given Classification Nodes via `POST /vault/items`, but you can add a classification to an existing Slot using `PUT /vault/slots/{id}`. Slots cannot be searched by Classification Node or Scheme. Some Slots have the type `classification_node`. The intent is that the owning Item will be classified with that node. Usually this is done within an app. # Attachments ## Attaching a File to an Item Every `item` in the meeco vault has the capability of having multiple files attached to it. The attachments are always attached to the `item` via a `slot` with the `slot_type` `attachment`. Assuming you have created an item already (such as the one you may have created in the getting-started page) and have the `.item.config` file still, lets create another item with that same config so as not to conflict with other steps later on in this guide. ```bash meeco items:create -i .item-config.yaml -a .alice.yaml > .item2.yaml ``` the next step is to create an `attachment-config.yaml` file with the following content. ```yaml kind: FileAttachment metadata: item_id: e8670e6c-8a95-43ff-a8d1-08805f612250 # (target item id from .item2.yaml) spec: label: 'Secret test webm video' file: './test.webm' ``` Then run the cli command ```bash meeco items:attach-file -c attachment-config.yaml -a .alice.yaml > .attach-response.yaml ``` You will get a response in the `attach-response.yaml` file that looks like the following ```yaml attachment: id: fe9ef5ad-b29c-4b71-bb73-b14fd4b88dca content_type: video/webm filename: test.webm ... slots: - id: 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b attachment_id: fe9ef5ad-b29c-4b71-bb73-b14fd4b88dca slot_type_name: attachment item_id: e8670e6c-8a95-43ff-a8d1-08805f612250 label: My Secret File encrypted_value: Aes256Gcm.z-T6OnEB6ssmkQK4RcvtYHjh2rE5PregqflhZoVXq6w=.QUAAAAAFaXYADAAAAAAhvEHoJqo845AsORoFYXQAEAAAAACahlEdh5rJcKfnl0DtTiaBAmFkAAUAAABub25lAAA= ... item: id: e8670e6c-8a95-43ff-a8d1-08805f612250 label: Item Label slot_ids: - 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b ... ``` Note: The slot's `encrypted_value` in this case is a new encryption key which has been encrypted with the user's own private data encryption key. The reason the file gets encrypted with a new data encryption key instead of directly with the user's existing private data encryption key has to do with sharing. By using this method when sharing, instead of having to re-encrypt the whole file with another data encryption key the slot's `encrypted_value` can simply be decrypted then re-encrypted with the data encryption key used for sharing. ## Downloading the Attached File To download an attached file the CLI needs to know the item's id and the slot's id, this is so the CLI can decrypt the data encryption key from the encrypted\_value of the slot (as mentioned above). Both of these values can be found in the `.attach-response.yaml` file under `slots[0].id` and `slots[0].item_id`. To download run the following ```bash meeco items:get-attachment e8670e6c-8a95-43ff-a8d1-08805f612250 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b -o ./output/ -a .alice.yaml # meeco items:get-attachment -o -a ``` ## Sharing and receiving the attachment Sharing an attachment simply works the same way you would share any other slot. First you will need to have a connection to another user, see the directions in the "Connections and Sharing" page to set up a connection first. Assuming you have a connection set up already and have the second user's info in a .bob.yaml file... Run the command ```bash meeco shares:create-config -i .item2.yaml -f .alice.yaml -c .connection.yaml > share-config2.yaml # meeco shares:create-config -i -f .alice.yaml -c > share-config.yaml ``` To create the share config then to create the share itself ```bash meeco shares:create -c share-config2.yaml > .create-shares-response.yaml ``` You should see some output like the following in the `.create-shares-response.yaml` file. ```yaml shares: - id: d9b68c36-110f-4171-8d9c-6bd580eff32d owner_id: c1f2485d-fe8d-4de2-b45f-deee52931207 sender_id: c1f2485d-fe8d-4de2-b45f-deee52931207 recipient_id: ca14e3ae-d7c9-49fe-85ec-ac3306414803 public_key: "..." encrypted_dek: Rsa4096.H-V2A_GlAbA3InFwKbdPoDVheM0p7kDIGg7tAtlnrF9-CFHtpo7pgE7MKBoszEp5jAkKwOlffZvaYt0ustjKb3yKDB-VKSKdZgu8yCkfJVNe8tgs5JpoZqg41krVrhVcUTLz6AsSfEXhnlFwKWLgbghqa7ad3u6LIGVVOTs_6-SBeuyJaYHDDBEN_TTiVqbIE7TU6LIUFSp38rpPOc0AM15FGZWhWcupYsy5gSO_jAOneBNi-sie392LX1LDPYbXi5fn-MSsWDektrR4bN0WlXA0iptTC-YqIrOFif9DFHL5qD5fis4Hfee95FCCPLBEtNoPNqU5u6YcE1a2XVlwPTMmeOVYDhHzl0HvT63QVc-zxhHqs3Tcg1mZtgDNb55qbUtNF8IGA1oOjG8LD69eIYOR3aO-cUs-iZcsZ-H0E7IqwX-bdCvZlLzUP1KI5sO3tIj32d9dCUCkvIJDf0TmPvB9UmF1rdoGDkT2dGvyGMA2sFQDhURq3I-NIOi4kp85h3l3JRN0BPcW1VzYCwX4Cn0HhG2brojv_Z8-j1QpCmOI9NO9XzJiMNi1ACMv-mJaEY4cBxvKtviY3eNaLsn8u-YrzH2InEOqrX7V9M2ynajf2YdJWxqCxUMXF_vWHxK04C6EQB2tdQ7SVNFchdjsuAjX-ue_RGmZ0hMNOXFCYjg=.QQUAAAAA terms: null expires_at: null ... ``` to see the incoming shared item first make a request for items as bob run ```bash meeco items:list -a .bob.yaml ``` you will see something like the following as output ```yaml kind: Items spec: - id: fce07d6a-0c6d-4615-acef-46beee08bb5f share_id: d9b68c36-110f-4171-8d9c-6bd580eff32d own: false name: item_label label: Item Label slot_ids: - 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 me: false background_color: null original_id: e8670e6c-8a95-43ff-a8d1-08805f612250 owner_id: c1f2485d-fe8d-4de2-b45f-deee52931207 ... ``` Notice how the `share_id` matches the share output from the previous command. We can then request the item itself. ```bash meeco items:get fce07d6a-0c6d-4615-acef-46beee08bb5f -a .bob.yaml # meeco items:get -a .bob.yaml ``` Returning ```yaml kind: Item spec: id: fce07d6a-0c6d-4615-acef-46beee08bb5f own: false label: Item Label slot_ids: - 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 original_id: e8670e6c-8a95-43ff-a8d1-08805f612250 owner_id: c1f2485d-fe8d-4de2-b45f-deee52931207 share_id: d9b68c36-110f-4171-8d9c-6bd580eff32d ... slots: - id: 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 own: false share_id: d9b68c36-110f-4171-8d9c-6bd580eff32d attachment_id: 4ac61cad-7911-46e9-a9f8-659b1eb79fc6 item_id: fce07d6a-0c6d-4615-acef-46beee08bb5f encrypted_value: Aes256Gcm.FYteKXIcTkjnC4OpqVcNFSzu5xwI3Eol0IubZUDpOhk=.QUAAAAAFaXYADAAAAACRE4YnWzELWDMfmE0FYXQAEAAAAACJtfJh93-EI7igsedpZ39aAmFkAAUAAABub25lAAA= label: My Secret File original_id: 67b2a8c2-4a4b-4a53-9b2f-5411cd63576b value: "´ž\x10¹(MKnCȏ«BêSD\x01ˆ¾†]V*Ç\x16qøÀ¡^ó" ... thumbnails: [] attachments: - id: 4ac61cad-7911-46e9-a9f8-659b1eb79fc6 content_type: video/webm filename: test.webm ... ``` Now we have all the information we need to be able to download the attached file ```bash meeco items:get-attachment fce07d6a-0c6d-4615-acef-46beee08bb5f 9ddaa9f7-b928-4727-a0ee-6dfb487ca0c8 -a .bob.yaml -o ./output/ # meeco items:get-attachment -a -o ``` ## Using the file-storage-browser or file-storage-node Packages The above flow is a great start to understanding how everything works however for actual product implementation these npm packages are likely to be more useful so please head to the following links and check out the README.md files there. file-storage-browser\ file-storage-node\ # On-sharing & Client Tasks ## Share Terms When sharing an item, a block of text can be added to the share, there is no required structure for these terms but something like the following should give you some idea of how it might be used. > I have allowed on-sharing on this item but before any on-sharing takes place call me on my phone to confirm it with me. or > This information on this item is being shared for the express purpose of applying for a home loan, it is not to be shared with anyone for the purposes of marketing or analysis. or > This information contains non-public business information and is for the eyes of Anthony Edward Stark only. ## Share Acceptance When creating a share there is an option to set whether acceptance of the terms and share is required, the settings allowed are `acceptance_required` and `acceptance_not_required`. Before the recipient of the share can view the data they must explicitly accept the share and it's terms via a second API call. For convenience when using the cli we have automatically set this feild to `acceptance_required` when any terms are specified. ## Sharing Mode When a user shares an item with another user there is an option to allow or dis-allow sharing of that item with another person, this is called the "sharing mode". The sharing mode currently has two options available on it, either `owner` or `anyone`. The `owner` sharing mode means the share can not be on-shared to another user. The `anyone` option means that the item can be on-shared to anyone. While the system will allow any on-sharing to happen when the sharing mode is set to `anyone` it is also important to check the `terms` that have set on the share. For convenience in the cli we have added the flag `--onshare` which will set the `sharing_mode` to `anyone` if it is present and set it to `owner` if it is not present. ## Client Tasks Due to use of e2e (end to end) encryption the client (client application) is the only place where data can be decrypted and re-encrypted. Sometimes there are tasks that do not need to happen right away when an action takes place but they will need to be done on the client at some point. An example of this is updating shares, for example... If a Alice has shared an item with Bob and some time later Alice changes the data in the shared item the share will also need to be updated.\ The data in Alice's items is encrypted with a DEK (data encryption key) that only Alice has access to, this means the server can not re-encrypt the data with a shared DEK on behalf of Alice, instead the server creates a `ClientTask`.\ Periodically Alice's client will check to see if there are any `ClientTask`s that need to be executed.\ Alice's client will pick up the `ClientTask` of type `update_shares` which will tell it to download and decrypt the modified item then re-encrypt the data with a shared DEK and update the share with the new data. ## Example of On-sharing and Executing Client Tasks (it's recommended to complete the getting-started/quickstart guide before follwing this example) (NOTE: each user will see the shared item as different `item_id`, when referencing the item by id be sure to use the `item_id` applicable to the user making the request) First lets create three users. ```bash meeco users:create -p supersecretpassword > .alice.yaml meeco users:create -p supersecretpassword > .bob.yaml meeco users:create -p supersecretpassword > .carlos.yaml ``` Next lets connect Alice to Bob, then Bob to Carlos. ```bash meeco connections:create-config --from .alice.yaml --to .bob.yaml > .connection1_config.yaml meeco connections:create -c .connection1_config.yaml > .connection1.yaml meeco connections:create-config --from .bob.yaml --to .carlos.yaml > .connection2_config.yaml meeco connections:create -c .connection2_config.yaml > .connection2.yaml ``` We create an item for Alice. ```bash meeco items:create-config vehicle -a .alice.yaml > .vehicle_config.yaml # open up the .vehicle.yaml and add an item label and other data meeco items:create -i .vehicle_config.yaml -a .alice.yaml > .vehicle.yaml ``` Share that item from Alice to Bob, with some share `terms`, `acceptance_required`, and sharing mode of `anyone`. ```bash meeco shares:create-config -i .vehicle.yaml -f .alice.yaml -c .connection1.yaml > .share1-config.yaml meeco shares:create \ --config .share1-config.yaml \ --onshare \ --terms="You may not use this information for advertising" \ > .share1.yaml ``` Read the share as Bob. ```bash meeco items:list -a .bob.yaml ``` You will get a result something like the following... ```yaml kind: Items spec: - id: 8e26d96f-7c15-444d-97a5-30e39b418c9d own: false label: DeLorean description: null created_at: 2020-10-12T05:52:45.395Z item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0 item_template_label: Vehicle slot_ids: - 642ea490-ccce-49cc-9fef-d5d9c6668549 ... me: false background_color: null original_id: dc66140c-3572-49b8-ad97-ec6de21827ba owner_id: 94c27129-e179-4c69-a7f1-94438b920541 share_id: b358bc99-89f1-48f3-8b84-8dad0516643e ... ``` Note the share\_id from above. Bob can have a look at the details and specifically the `terms` of the share by getting the share's details with the command. ```bash meeco shares:get-incoming -a .bob.yaml $EXISTING_SHARE_ID ``` Note that the item slot details are not available to Bob until he accepts the share and it's terms. Next Bob will accept the share from Alice. ```bash meeco shares:accept -y $EXISTING_SHARE_ID -a .bob.yaml ``` Bob can now pull down the item's details. (Note: the item id must come from the item when performing the items:list command, the item\_id in the shares:accept command will not work). ```bash meeco items:get 8e26d96f-7c15-444d-97a5-30e39b418c9d -a .bob.yaml > .shared-to-bob-item.yaml # meeco items:get -a ``` Now Bob can share this item with Carlos. ```bash meeco shares:create-config -i .shared-to-bob-item.yaml -f .bob.yaml -c .connection2.yaml > .share2-config.yaml meeco shares:create \ --config .share2-config.yaml \ --terms="You may not use this information for advertising" \ > .share2.yaml ``` Carlos can now see the share. ```bash meeco items:list -a .carlos.yaml ``` Returning something like... ```yaml kind: Items spec: - id: 59cb375f-6188-46fd-bdd6-ba730ae3282c own: false label: DeLorean description: null created_at: 2020-10-13T05:41:02.376Z item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0 item_template_label: Vehicle slot_ids: - e90e38f2-65d7-4203-b74f-0831dab393c1 ... original_id: dc66140c-3572-49b8-ad97-ec6de21827ba owner_id: 94c27129-e179-4c69-a7f1-94438b920541 share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c ``` Noting the share\_id and item\_id from the above command. Accept it. ```bash meeco shares:accept $EXISTING_SHARE2_ID -a .carlos.yaml ``` And view it. ```bash meeco shares:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yaml # or meeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml ``` Getting the output something like... ```yaml kind: Item spec: id: 59cb375f-6188-46fd-bdd6-ba730ae3282c own: false label: DeLorean item_template_id: 311422ef-9546-404b-92c4-483a7ce3ebd0 item_template_label: Vehicle slot_ids: - 81cc655f-5ae8-4a7a-afc0-3d186ab3f736 ... me: false background_color: null original_id: dc66140c-3572-49b8-ad97-ec6de21827ba owner_id: 94c27129-e179-4c69-a7f1-94438b920541 share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c slots: - id: 81cc655f-5ae8-4a7a-afc0-3d186ab3f736 own: false share_id: 47b22868-99c1-4b8b-b9d5-e0ec0830c31c name: licence_plate item_id: 59cb375f-6188-46fd-bdd6-ba730ae3282c slot_type_name: key_value encrypted_value: Aes256Gcm.AjR9r_An-mcqLla1dcGL.QUAAAAAFaXYADAAAAACcR_n2XVORiZ2wRjgFYXQAEAAAAACCNE5L6Gqq-4Zmm5Y8AgVEAmFkAAUAAABub25lAAA= encrypted_value_verification_key: Aes256Gcm.f4af1rELcDkDJQv7wPsfvOOVbnI6YyQlsnYLdDdekAZ2AcXm6Oq7WrgGytc3gUbvjnWvmkzAnWO2s2Kya0ZxLQ==.QUAAAAAFaXYADAAAAABQ346yXewWcSdSdBEFYXQAEAAAAACyZph19u-eZ-BWMPhrOqP4AmFkAAUAAABub25lAAA= value_verification_hash: d8c6e5f28837906505fa9e6a4740c8ddd5dddbe4b51675ae3daabef4a27d701b label: Vehicle registration number original_id: 5503d256-19d6-45f8-b76b-9605f977cd3f owner_id: 94c27129-e179-4c69-a7f1-94438b920541 value: NotACatDefsACar value_verification_key: "5ÁÑ\x1a”=Ù¯\a\a\x1f|1\v§ì¨Nqe¡b\x05Ç\rr’v—ý[nê\x05À\x11ޜBïǚí\eé\x14y\ há_éû›Cz)žêö\0ۊ]³" ... ... thumbnails: [] attachments: [] ... ``` So now we have an Item on-shared from Alice to Bob to Carlos. What if Alice now wants to update the item and get Bob and Carlos the updated data? First Alice updates the item. ```bash meeco items:get $VEHICLE_ITEM_ID -a .alice.yaml > .existing_vehicle_item.yaml # edit the .existing_vehicle_item.yaml file, specifically the `value` fields of the `slots` and/or the `label` field of the `item` then... meeco items:update -i .existing_vehicle_item.yaml -a .alice.yaml ``` Ok, the item has been updated at this stage but not the shares. Note that the last line of the `items:update` command showed a comment saying ```bash # Item updated. There are 1 outstanding client tasks. Todo: 1 & InProgress: 0 ``` If we request the list of Client tasks with the following command... ```bash meeco client-task-queue:list -a .alice.yaml ``` We will see a list of ClientTasks that are outstanding something like the following. ```yaml kind: ClientTaskQueue spec: - id: 0de4fb1a-6c43-4ca5-8880-c5187df3972b state: todo work_type: update_item_shares target_id: dc66140c-3572-49b8-ad97-ec6de21827ba additional_options: {} last_state_transition_at: null report: {} created_at: 2020-10-13T06:02:55.028Z ``` What we need to do next is re-encrypt all the new data with a new DEK to share with both Bob and Carlos. We can do this by running the command. ```bash meeco client-task-queue:run-batch -a .alice.yaml ``` You will see the output something like the following. ```yaml completedTasks: - id: 0de4fb1a-6c43-4ca5-8880-c5187df3972b state: todo work_type: update_item_shares target_id: dc66140c-3572-49b8-ad97-ec6de21827ba additional_options: {} last_state_transition_at: null report: {} created_at: 2020-10-13T06:02:55.028Z failedTasks: [] ``` Now Carlos and Bob have the updated shared data, you can check that by running the commands. ```bash meeco shares:get-incoming $BOB_SHARED_INCOMING_SHARE_ID -a .carlos.yaml or meeco items:get $BOB_SHARED_INCOMING_ITEM_ID -a .bob.yaml meeco shares:get-incoming $CARLOS_SHARED_INCOMING_SHARE_ID -a .carlos.yaml or meeco items:get $CARLOS_SHARED_INCOMING_ITEM_ID -a .carlos.yaml ``` Hopefully this guide has given you a decent high level overview of how the process works.\ To dig further into the functionality why not try checking out how the CLI () uses the underlying SDK (). # Account Delegation ## What is account delegation Account delegation provides access and/or control over your private encrypted data to another user. The intended purpose for this feature is to allow people you trust full access. In almost all cases we recommend using Shares and On-Shares to give access to other users as it gives much more granular control over the data shared to another user. An example where you might use a feature like this is where a user is helping a family member (be that a child or an elderly parent) who requires assistance. ## Setting up delegation ### Setting up the Scenario First lets create two new users to set up a delegation between. ```bash meeco users:create -p password > .riker.yaml meeco users:create -p password > .homer.yaml ``` Next lets create an item in Riker's account so we can later test to make sure Homer has access to it. ```bash # List out available templates meeco templates:list -a .riker.yaml # Create an item config file from one of the chosen templates meeco items:create-config vehicle -a .riker.yaml > .riker-vehicle-config.yaml # Extra step, open up the above item config yaml file and modify it in your chosen text editor # Create the item using the above item config yaml meeco items:create -i .riker-vehicle-config.yaml -a .riker.yaml > .riker-vehicle.yaml ``` ### Creating the Delegation Connection Next lets get Riker to create a delegation connection invitation with the delegation role `reader`. (delegation-role options are `owner`, `admin`, and `reader`) ```bash meeco delegations:create-invitation -a .riker.yaml Homer reader > .delegation-invitation.yaml ``` Homer can now accept that delegation connection invitation from Riker and the delegation connection will have been created. ```bash meeco delegations:accept-invitation -a .homer.yaml -c .delegation-invitation.yaml Riker > .delegation-connection.yaml ``` ### Sharing the Key Encryption Key While the connection has been created There are still a couple more steps to go before the delegation has been fully set up. These steps are for sharing Riker's Key Encryption Key (KEK) to Homer. First Riker must Encrypt his KEK with Homer's public key and send it. ```bash # meeco delegations:share-kek -a .riker.yaml meeco delegations:share-kek 53cbd900-6657-40a0-9fae-ad8ac20078f4 -a .riker.yaml ``` Next Homer accepts Riker's KEK, decrypting it with his private key, then storing it for access later under his own KEK. ```bash # meeco delegations:accept-kek -a .homer.yaml meeco delegations:accept-kek 099ebb9b-b49f-4c20-8606-b92b7dcc8ea6 -a .homer.yaml ``` ### Reading User data as a delegate user First Homer can pre-load Riker's KEK and Private DEK should for decrypting the data. ```bash # meeco delegations:load-auth-config --delegationId -a .homer.yaml > .homer-with-riker-delegation.yaml meeco delegations:load-auth-config --delegationId c0181886-20de-45de-b4b5-b614f92f2440 -a .homer.yaml > .homer-with-riker-delegation.yaml ``` Next Homer can list out the Riker's items. ```bash # meeco items:list --delegationId -a .homer.yaml meeco items:list --delegationId c0181886-20de-45de-b4b5-b614f92f2440 -a .homer-with-riker-delegation.yaml ``` Then, taking note of the item id from the items:list command, finally Homer can view the item Riker created earlier. ```bash # meeco items:get --delegationId -a .homer-with-riker-delegation.yaml meeco items:get --delegationId c0181886-20de-45de-b4b5-b614f92f2440 0f0dc0d3-d7f4-42e6-8b46-e41bf3a51d2a -a .homer-with-riker-delegation.yaml ``` # Machine-2-Machine Communication Tenant and Organisation Administrators can provide an application with authenticated access to SVX functionality. This allows the application to perform different actions based on the permissions of the Tenant or Organisation Administrator creating the application. Applications created by Tenant Administrators will be able to: * Invite and remove end-users * Manage credential schemas Applications created by Organisation Administrators will be able to: * Create and archive credential templates * Issue and revoke credentials * Create and archive verification templates * Create verification requests and view verification responses * Create and cancel connections with end-users ### Access the SVX Sandbox API and create an application To access the SVX Sandbox API and create an application you will need to follow the steps below: **1. Access the SVX Sandbox API documentation** Navigate to [SVX Sandbox API documentation](https://api-reference-sandbox.svx.exchange/). At the top of the landing page, you will see the OpenAPI3 specification. Download the specification and import it into [Postman](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/). > **Note** To download the OpenAPI3 specification into Postman, follow these simple steps: > > 1. Download the specification from the [SVX API documentation](https://api-reference-sandbox.svx.exchange/) > 2. Open Postman > 3. Import the downloaded .json file **2. Create an application** Log in to the [SVX Portal](https://portal-sandbox.securevalueexchange.com/login) and create an application, see the Applications tutorial located in the [Portal tutorials](/svx-v3/guides/portal-tutorials) for more information. > **Note** Tenant and Organisation Administrators can both create Applications, however, different workflows are achieved based on the associated role and access rights. > **Note** Once an application has been created, ensure you record the `client_id` and `client-secret`. **3. Open the API configuration** View the Open API configuration at and retrieve your authorisation token. Use the token endpoint from the configuration () to obtain an authorisation token. You can do this using the cURL command as shown below: ```bash curl -X POST https://login-sandbox.securevalueexchange.com/oauth2/token \ -d 'grant_type=client_credentials' \ -d 'client_id=YOUR_CLIENT_ID' \ -d 'client_secret=YOUR_CLIENT_SECRET' ``` Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with the actual values you obtained when creating the application. > **Note** The Application Token will expire every 10 minutes. To refresh the token you will need to call the token endpoint again. **4. Access the SVX Sandbox API** With the obtained authorisation token, you can now use the SVX Sandbox API. For example, if you want to access the me endpoint, use the following cURL command: ```bash curl --location 'https://api-sandbox.svx.exchange/me' \ --header 'Meeco-Organisation-Id: YOUR_ORGANISATION_ID' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' ``` Replace `YOUR_ORGANISATION_ID` with the relevant ID for your organisation, and `YOUR_ACCESS_TOKEN` with the token obtained in the previous step. You should now be able to successfully access the SVX Sandbox API using the provided authorisation token. # Portal Tutorials The following are step-by-step tutorials and contextual information relating to workflows via the SVX Portal. # Tenant Administrators The following are step-by-step guides and contextual information relating to workflows undertaken by Tenant Administrators in the SVX Portal. # Onboard to a Tenancy ### Invitation emails Tenants are managed by Tenant Administrators. Tenant Administrators gain access to a Tenancy via an invitation email. The first Tenant Administrator to join a Tenancy will receive an invitation email from a Meeco Administrator. Subsequent Tenant Administrators can be invited by existing Tenant Administrators. To accept an invitation email, navigate to your email inbox. Locate the email sent from *SVX Support* with the subject heading *Invite to join (Tenant name) Tenancy*. #### First time invitation to the SVX Portal If this is your first invitation to join SVX, the email will contain: * The name of the person who invited you, and * Steps on how to access the SVX Portal. These steps include: * Navigating to the registration URL * Entering your temporary password * Setting a new password After clicking on the registration URL, you will be presented with the SVX registration screen. Enter the temporary password that was provided to you, set your new password and accept Meeco’s [Privacy Policy](https://www.meeco.me/privacy-policy) and [Terms and Conditions](https://www.meeco.me/terms). Click *Next* to log in. You will land on the Tenant selection screen. Click on your Tenant and you will land on the associated Dashboard.
How to onboard to a Tenancy as a new user tutorial video.
#### Subsequent invitations to the SVX Portal It is possible for a Tenant Administrator to be invited to join other Tenancies and / or Organisations. In this case, the SVX Portal will recognise the Tenant Administrator as an existing Portal user. All subsequent invitation emails will state: * Which Tenant or Organisation you have been invited to join * The name of the person who invited you * A URL to access the SVX Portal, and * A reminder to use your existing login details After clicking on the *Portal Login* URL, you will be presented with the SVX login screen. Enter your email address (as your username) and your password. Click *Log in* to continue to the SVX Portal. You will land on the Tenant selection screen. Click on your Tenant or Organisation to navigate to the associated Dashboard. > **Note** If you are joining an Organisation you will be asked to either set up or enter the Organisation's Passphrase. For more information, see the [Onboarding and Organisation Setup](/svx-v3/guides/portal-tutorials/organisation-administrators/onboarding-and-organisation-setup) tutorial.
How to onboard to a Tenancy as an existing user tutorial video.
### Accessing the SVX Portal The SVX Portal can be accessed via: # Dashboard and Navigation ### Dashboard After logging into a Tenant, Tenant Administrators are presented with their Tenant Dashboard. The Dashboard contains quick links that enable the Administrator to perform actions within the SVX Portal. These quick links are presented as tiles. Each tile displays a section of the Portal and a brief description of the actions a user can take within that section. The tiles that appear on a Tenant Dashboard include: * Organisations * Credentials * Manage Tenancy * Documentation * Helpdesk
### Navigation #### Toolbar The toolbar appears at the top of the Portal user interface (UI) and is permanently visible.
Three icons appear in the top-right corner of the toolbar: * Security * Documentation * Helpdesk All three icons enable Administrators to navigate to external resource sites, however, the security icon also acts as a visual indicator of secure information being presented on the screen (see below for more details).
#### Security The security icon only appears on the toolbar on pages that contain a security component. These security components contain personally identifiable information (PII) and are only visible to Administrators with the assocaited permissions. These components can be identified via the security icon centred in a green circle in the top-left of the component's heading. They also have a grey background that creates a box for the private information to sit inside. If an Adminsitrator does not have the required permissions to view the sensitive information, a condensed security component will be visible with the following text *"You do not have permission to view this information. To view this information enter the Organisation’s passphrase."*. > **Why is this important?** This icon indicates to Administrators which personally identifiable information (PII), or other sensitive data is visible to them (or not) based on their access permissions. This is important as sensitive data should only be accessible to authorised users.
When a user lands on a page that has a security container component, or when a user closes a security explainer component, a green ring around the security icon on the toolbar will animate (the green circle will loop twice around the icon). When hovering over the security icon, or after clicking the icon on the toolbar, a message will appear below stating ***“Privately viewed information.** This information is only visible to Organisation Administrators with the associated permissions.”*
#### Documentation When hovering over the documentation icon, a message will appear below stating ***“Documentation.** Click to navigate to SVX documentation.”* After clicking on the documentation icon, you will be taken to the SVX supporting [documentation landing page](https://docs.meeco.me/). Here you will find API documentation and step-by-step tutorials.
#### Helpdesk When hovering over the helpdesk icon, a message will appear below stating ***“Helpdesk.** Click to navigate to the SVX Helpdesk. Lodge help requests, bug reports, or suggestions.”* After clicking on the helpdesk icon, you will be taken to the SVX Helpdesk landing page. Via the SVX Helpdesk landing page, Administrators can choose to lodge help requests, bug reports, or suggestions. These requests will be recorded and given a unique identifier. Status updates and correspondence regarding a request will be available to the Administrator who lodged it. Correspondence and notifications will be sent to the Administrator via their registered email address. #### Side Menu A Tenant Administrator’s side menu in the SVX Portal consists of the following sections and sub-sections: * Dashboard * Organisations * Credentials * Credential schemas * Devtools * Applications * Documentation * Helpdesk * Manage Tenancy * Administrators * End Users * Account Settings #### Side menu footer At the bottom of the side menu, you will see the footer. The footer displays your name and a link to *Manage Account*. Alongside, is an arrow icon ⌃ where, when clicked, presents additional menu options: **My Profile** Within the *My Profile* section you are able to manage your SVX account, including your profile information and password. For more information, see the [Manage Account](/svx-v3/guides/portal-tutorials/tenant-administrators/manage-account) guide. **Switch Tenant or Organisation** If you are an Administrator of multiple Tenants and / or Organisations you can click the *Switch Tenant or Organisation* button. From here, you will be presented with a summary of the Tenants and / or Organisations you are associated with. Via the left-side menu of the SVX Portal, you can navigate between the *Tenants* and *Organisations* sections. After clicking on a section, you will be presented with a table listing all Tenants / Organisations. Above the table are tabs that allow you to view Current and Archived Tenants and Organisations. Click on a Tenant or Organisation to navigate to the corresponding Dashboard.
How to switch contexts tutorial video.
**Logout** If you wish to logout of the SVX Portal, navigate to the side menu footer, click on the arrow icon ⌃ and click on *Logout*. You will be presented with a confirmation message asking you to confirm that you wish to logout. Click the button *Yes, log me out* to complete the logout workflow. Alternatively, if you wish to remain logged in, click the button *No, keep me logged in*.
How to log out of the Portal tutorial video.
# Manage Account Within the *Manage Account* section of the side menu footer, you can manage the following: * Profile details * Security (password management) ## Profile details ### View Profile details Tenant Administrators can view their profile details by navigating to *Manage Account* on the left-side menu footer of the SVX Portal, and selecting the *Profile* tab. Here you will see your: * Given name * Family name * Email * User ID > **Note** The *User ID* is designated by the SVX Portal at the time the Administrator is created. ### Edit Profile details To edit your profile details, select the *Edit* button on the *Profile* page. The information will be presented as an editable form where you can update / change the following information: * Given name * Family name When complete, select *Save* to save changes, or *Cancel* to discard changes. > **Note** Your *email address* and *User ID* cannot be changed as they are tied together. At this point in time, an Administrator can only have one email address linked to their profile within SVX.
How to view and edit an Administrator's profile details tutorial video.
## Security ### Change your password Tenant Administrators can change their SVX password by navigating to *Manage Account* on the left-side menu footer of the SVX Portal, and selecting the *Security* tab. To change your password, you will need to enter the following information into the presented form: * Current password * New password * Confirm new password When complete, select *Save* to save changes, or *Cancel* to discard changes.
How to change an Administrator's password tutorial video.
# Manage Tenancy Within the Manage Tenancy section of the side menu, you can manage the following: * Administrators, see the [Manage Tenant Administrators](/svx-v3/guides/portal-tutorials/tenant-administrators/manage-tenant-administrators) tutorial for more information. * End Users, see the [End Users](/svx-v3/guides/portal-tutorials/tenant-administrators/end-users) tutorial for more information. * Account Settings ### View Account Settings Tenant Administrators can view their Tenancy’s account settings by navigating to *Manage Tenancy* on the left-side menu of the SVX Portal, and selecting *Account Settings*. Here you will see the: * Tenant name * Tenant ID * Logo URL > **Note** The *Tenant ID* is designated by the SVX Portal at the time the Tenancy is created. ### Edit Account Settings To edit your Tenancy’s details, select the *Edit* button from the *Account Settings* page. The information will be presented as an editable form where you can update / change the following information: * Tenant name * Logo To change the Tenant’s logo either drag and drop the new logo file into the outlined logo box or select *click here* to navigate to the new logo’s location on your device. The new logo will appear in the preview box. When complete, select *Save* to save changes, or *Cancel* to discard changes. > **Note** The *Tenant ID* cannot be changed. You can, however, click on the copy icon to copy the ID to your clipboard. # Manage Tenant Administrators ### Add a Tenant Administrator to a Tenant All Tenant Administrators are able to invite new Administrators to join their Tenancy. To do this, navigate to *Manage Tenancy* on the left-side menu of the SVX Portal and select *Administrators*. Select the *Add new administrator* button. You will be presented with a form where you will need to enter the details of the new administrator: * First name * Surname * Email address You will also have the option to include a message that will be delivered to the administrator via the automatically generated invitation email. Once all required fields are complete select the *Add* button and the Tenant Administrator will appear in the list of *Pending Administrators*. > **Note** Once the invited administrator accepts the invitation to join the SVX Portal they will appear in the *Current Administrators* list.
How to add a Tenant Administrator to a Tenant tutorial video.
### Resend an invitation to join a Tenant Tenant Administrators are able to resend invitations to invited administrators. To resend an invitation, navigate to *Manage Tenancy* on the left-side menu of the SVX Portal and select *Administrators*. Select the *Pending Administrators* tab and locate the invitee in the list. Select the horizontal ellipsis icon ⋯ alongside the invitee’s name to reveal menu options. Select *Resend invitation* and the onboarding email will automatically be resent to the designated recipient.
How to resend an invitation to join a Tenant tutorial video.
### View a Tenant Administrator’s details To view the details of a Tenant Administrator within a Tenant, navigate to *Manage Tenancy* on the left-side menu of the SVX Portal and select *Administrators*. Locate the administrator in one of the navigation tabs. Select the horizontal ellipsis icon ⋯ alongside the administrator’s name to reveal menu options. Select *View*. You will be presented with the following information: * Administrator ID * Given name * Family name * Email * Tenant name * Tenant ID
How to view a Tenant Administrator's details tutorial video.
### Remove a Tenant Administrator from a Tenant To remove a Tenant Administrator from a Tenant, navigate to *Manage Tenancy* on the left-side menu of the SVX Portal and select *Administrators*. Locate the administrator in either the *Current Administrators* or the *Pending Administrators* tabs. Select the horizontal ellipsis icon ⋯ alongside the administrator's name to reveal menu options. Select *Remove* and confirm the removal of the administrator via the modal window. The administrator will be removed from the Tenant, and their name will be moved to the *Removed Administrators* tab. > **Note** *Removing a Tenant Administrator:* Once removed from a Tenant, the administrator will no longer be able to access the Tenant or its functions. Note that administrators can be reinstated if required.
How to remove a Tenant Administrator from a Tenant tutorial video.
### Reinstate a Tenant Administrator to a Tenant To reinstate a Tenant Administrator to a Tenant, navigate to *Manage Tenancy* on the left-side menu of the SVX Portal and select *Administrators*. Select the *Archived Administrators* tab and locate the administrator in the list. Select the horizontal ellipsis icon ⋯ alongside the administrator's name to reveal menu options. Select *Reinstate* and confirm the reinstating of the administrator via the modal window. The administrator will be reinstated in the Tenant, and their name will be moved to the *Current Administrators* tab.
How to reinstate a Tenant Administrator to a Tenant tutorial video.
# Manage Organisations ### Add an Organisation to a Tenant Tenant Administrators can add Organisations to their Tenancy by navigating to *Organisations* on the left-side menu of the SVX Portal. Select the *Add new organisation* button. You will be presented with a form consisting of the following fields: * Organisation name * Organisation URL * Associated schemas (made available to Organisations) * Logo upload > **Note** *Associated schemas:* For more information on creating, managing and assigning schemas to Organisations, see the tutorial [Credential Schemas](/svx-v3/guides/portal-tutorials/tenant-administrators/credential-schemas). Once all required fields are complete select the *Add* button and the Organisation will appear in the list. > **Note** The Tenant Administrator who creates the Organisation will automatically become the Organisation's first Administrator. This allows you to invite other Organisation Administrators to join. It also provides you with access to the Organisation's context by clicking on the Organisation's name in the list. > After entering the Organisation's context, you will be asked to set up the Organisation's [passphrase](/svx-v3/concepts/terminology#passphrase). Meeco strongly advises that you do not set up the Organisation's [passphrase](/svx-v3/concepts/terminology#passphrase). Instead, allow a known, invited member of the Organisation to set up the [passphrase](/svx-v3/concepts/terminology#passphrase) when they first log in to the Portal. For more information, see the [Onboarding and Organisation Setup](/svx-v3/guides/portal-tutorials/organisation-administrators/onboarding-and-organisation-setup) tutorial.
How to add an Organisation to a Tenant tutorial video.
### View and edit an Organisation’s details To view the details of an Organisation within a Tenant, navigate to *Organisations* on the left-side menu of the SVX Portal. Locate the Organisation in the list and select the horizontal ellipsis icon ⋯ alongside the Organisation’s name to reveal menu options. Select *View*. You will be presented with a *Details* screen that lists the following information: * Organisation Name * Organisation URL * Organisation ID * Organisation DID * Associated Schema(s) * Logo To edit the Organisation’s details, select the *Edit* button from the *Details* page or select *Edit* from the horizontal ellipsis icon ⋯ alongside the Organisation’s name. The information will be presented as an editable form where you can update / change the following information: * Organisation Name * Organisation URL * Associated Schema(s) * Logo When complete, select Update to save changes, or Cancel to discard changes. > **Note** The Organisation’s *ID* and *DID* cannot be edited. These are system-generated identifiers that remain with the Organisation once it is created.
How to view and edit an Organisation tutorial video.
### Archive an Organisation To archive an Organisation within a Tenant, navigate to *Organisations* on the left-side menu of the SVX Portal. Locate the Organisation in the *Current Organisations* list and select the horizontal ellipsis icon ⋯ alongside the Organisation’s name to reveal menu options. Select *Archive* and confirm the archiving of the Organisation via the modal window. The Organisation will be removed from the Tenant, and will be moved to the *Removed Administrators* tab. > **Note** *Archiving an Organisation:* Once removed from a Tenant, all associated Organisation Administrators will no longer be able to access the Organisation or its functions, this includes the management of: > > * Credential Templates > * Credential issuance and revocation > * Verification Templates > * Request for Credentials > * Connection with End Users > * Applications Note that Organisations can be reinstated if required and full functionality will be restored.
How to archive an Organisation tutorial video.
### Reinstate an Organisation To reinstate an Organisation to a Tenant, navigate to *Organisations* on the left-side menu of the SVX Portal. Locate the Organisation in the *Archived Organisations* list and select the horizontal ellipsis icon ⋯ alongside the Organisation’s name to reveal menu options. Select *Reinstate* and confirm the reinstating of the Organisation via the modal window. The Organisation will be reinstated to the Tenant, and will be moved to the *Current Administrators* tab.
How to reinstate an Organisation tutorial video.
### View an Organisation from the Organisation's context To view an Organisation within the Organisation's context you must first be an Administrator of the Organisation. While Tenant Administators can add themselves as Organisation Administrators, without an Organisation's [passphrase](/svx-v3/concepts/terminology#passphrase) you will have limited access to the Organisation and its functionality within the Portal. To obtain full access to the Organisation, you will need to enter the Organisation's [passphrase](/svx-v3/concepts/terminology#passphrase). > **Note** Meeco strongly advises that you first obtain consent from the Organisation to be added as an Administrator. After obtaining the Organisation's passphrase, you will be able to undertake actions on behalf of the Organisation. For more information, see the following tutorials: [Manage Organisation Administrators](/svx-v3/guides/portal-tutorials/tenant-administrators/manage-organisation-administrators) and [Onboarding and Organisation Setup](/svx-v3/guides/portal-tutorials/organisation-administrators/onboarding-and-organisation-setup). --- [Next Page](/llms-full.txt/1)