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​
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​
Item — Contains one or more slots with filled in values. Read more about Items in the Terminology section​
Browsing Item Templates
Items are created from templates, so we begin by listing all available Item templates:
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​
(Get API_SUBSCRIPTION_KEY by signing up for the API, then use the CLI tool to generate a User and access token.)
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:
{
    "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):
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​
Or, to search Item Templates by matching label text (replace SEARCH_TEXT):
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​
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 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:
  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​
The API response is the newly created Item:
{
    "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.
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.
    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:
{
  "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:
  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.
{
  "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:
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 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:
cryppo genkey
Result:
URL-Safe Base64 encoded key:
3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg=
To encrypt slot value `BMW` run the following command:
cryppo encrypt -v BMW -k 3YazDa71zVVCzh_6JRd_M-J5bOKUS5HtFGLNR45prPg=
Result:
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:
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​
The example below creates an Item config file. We need to provide a template name to create an item config file.
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:
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:
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:
{
  "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 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.
Property	Description
`name`	Machine-readable string
`label`	Display name
`description`	Longer name
`encrypted_value`	Output of Cryppo encryption
`slot_type_name`	string
Property	Owner Vaule	Receiver Value
`own`	true	false
`original_id`	null	`share.item_id`
`share_id`	null	`share.id`
Last modified 1yr ago