Items and Slots
Last updated
Was this helpful?
Last updated
Was this helpful?
This guide describes creating Items and Item Templates using the Meeco API.
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 page.
Items are created from templates, so we begin by listing all available Item templates:
(Get API_SUBSCRIPTION_KEY by for the API, then use the CLI tool to .)
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:
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
You can get a specific Template using its id (replace ITEM-TEMPLATE-ID):
Or, to search Item Templates by matching label text (replace SEARCH_TEXT):
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
To create an Item you must give the name of an existing Item Template, and a label:
The API response is the newly created Item:
Notice that Slots are created according to the Item Template, but are left empty for now.
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.
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
Then the new Item will have Slots foo, bar and baz.
The next section has more information about creating Slots.
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 new Template will look like this:
Then, you can create an item from your new template:
The created item comes back looking like the following, with a custom slot that was part of the template creation call.
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 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:
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.
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.
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:
Result:
To encrypt slot value `BMW` run the following command:
Result:
The output above is the encrypted slot value ready to be stored in the Vault.
We can decrypt by running the following command:
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
The example below creates an Item config file. We need to provide a template name to create an item config file.
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:
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.
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:
Response:
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!
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.
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.
For now the new Item's Slots are left empty. A will cover encrypting data and adding it to a created Item.
Items can also be classified, that is described in .
To get familiar with the kinds of cryptographic key the Meeco platform uses please follow either the 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.
If you are feeling adventurous you are welcome to dig into the
The page on covers sharing Items. This section will just describe some properties of shared Items.