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 page.
Browsing Item Templates
Items are created from templates, so we begin by listing all available Item templates:
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.
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.
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
{"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.
The created item comes back looking like the following, with a custom slot that was part of the template creation call.
{"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:
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 guide, or "Setting Up Access to the Vault and Keystore". 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:
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:
meecoitems: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:
The page on 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.
