Skip to main content

Boxes

The box concept is described here.

tip

Need some changes ? More endpoints ? Please open a github issue or contact us at love@misakey.com.

Create a box#

A box should be created with a datatag and a data subject.

The data subject is supposed to be the email of the person concerned by the data. After being connected on Misakey using this email, data subjects can see boxes you have created and linked to their email. They have access to the box and its data.

info

Do not forget to save the id of the created box to later send data to it.

Request#

POST https://api.misakey.com/organizations/:oid/boxes
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • oid (uuid string): your organization id.

JSON Body:

{
"title": "Requête RGPD",
"owner_org_id": "d1e9bfa6-e931-46b1-b73c-77cb3530aadb",
"datatag_id": "b7073bc5-b2e8-4a22-9717-8418de13bfa5",
"data_subject": "michel@misakey.com",
"public_key": "SXvalkvhuhcj2UiaS4d0Q3OeuHOhMVeQT7ZGfCH2YCw",
"key_share": {
"misakey_share": "lBHT1vfwFAIBig5Nj_sD_w",
"invitation_share_hash": "Nz4nJMj5DOd4UGXXOlH8Ww",
"encrypted_invitation_key_share": "cGYMzgIO9rc03WoSLAyoiQdLu7he5VbMRImLhRPmwTQ"
},
"crypto": {
"invitation_data": {
"eu87vEFWxCZcJaQSqiLMGMNvVlsp9uMO97SZcyHctRjsD9JpCrFMyfMMwwE7g_PHsesHQDGsO1sGi6z2TbOB-g": "fbs05eripjc7PkZsmeBPFRxwpfj_0ARt6QjaO3B2PpIvLxaTVDvSfW6_V97HUxA7qDN5vTdi5xWq"
},
"provisions": {
"michel@misakey.com": {
"public_key": "eu87vEFWxCZcJaQSqiLMGMNvVlsp9uMO97SZcyHctRjsD9JpCrFMyfMMwwE7g_PHsesHQDGsO1sGi6z2TbOB-g",
"misakey_key_share": "9ALK2WOpvEmOJx7WUWVOg-68IIc8lJl8I8CxMeLg4EuGiaz8JwRDVgAT7LV7ATHManMcS3NRhlNXy5T3FVvu_Q",
"user_key_share_hash": "fDy_i2AGOQFKj_kJ061Up_ob1YyHIUl-0lhiFMAkjWYLnOzhN3t5R9H1MWhBQw4zVKLzaXblVvGnvsH_Mmxx8Q"
}
}
}
}
  • title: (string) a free text that is meant to describe the box purpose for the end-users
  • owner_org_id: (string) your organization id
  • datatag_id: (string) the datatag id
  • datatag_subject: (string) email of the person concerned by the data
  • public_key: (string, unpadded url-safe base64): the public key of the box. If it is for com.misakey.aes-rsa-enc algorithm, it must be prefixed with com.misakey.aes-rsa-enc:
  • key_share: (object) (optional) see the key share guide for more information
  • crypto: (object) (optional) data used for cryptographic side-effects of the creation of the box (creation of cryptogrpahic auto-invitations, of crypto provisions, etc ...)
  • crypto.invitation_data: (object) (optional) the auto-invitations to create together with this box. This is a mapping from public keys to invitation encrypted payload. See the auto invitation reference about how to create auto invitations.
  • crypto.provisions: (object) (optional) see the crypto provisions guide
tip

It is recommended to use key_share to have a way to share the crypto materials to the data subject.

Note that the access mode of a box is limited by default. A state.access_mode event must be created to switch it to public, see the related event type documentation.

Response#

HTTP 201 Created

JSON Body:

{
"id": "c3fde689-5d4e-4f1b-813f-f9cdb05547ce",
"title": "Test Box",
"owner_org_id": "642ef87f-2902-4316-9cd1-afa887824f53",
"datatag_id": "d5e1374f-e563-4322-b8e8-94bd12cd7a38",
"data_subject": "823a59-test@misakey.com",
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"access_mode": "limited",
"server_created_at": "2021-03-10T14:14:03.76932Z"
}

The most important part is the id field which must be used to interact with the box.

Boxes search#

Count boxes#

It is possible to count boxes with optional filtering using query parameters. This can be use to handle in amount pagination for listing.

Only boxes you have access to will be counted.

Request#

HEAD https://api.misakey.com/boxes
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Query Parameters: To filter more precisely your request:

  • owner_org_id: (optional) (string, uuid) the organization id which is owner of the box. Default: the organization id making the request.
  • datatag_ids: (optional) (comma-separated list of strings, uuid) ids of datatag you want to retrieve. "" for boxes with no datatag. Default: all. Example: datatag_ids=7523588e-9c3d-4c9d-83b7-d98663bf1215,d9c01c3e-955a-4e98-b9f7-2610cc857108,"".
  • data_subject: (optional) (string) the subject value (identifier value - email). Default: all.

Response#

Code:

HTTP 204 No Content

Headers:

  • X-Total-Count (integer): the total count of boxes considering filters.

List boxes#

It is possible to retrieve a list of boxes with optional filtering using query parameters.

Only boxes you have access to will be returned.

Request#

GET https://api.misakey.com/boxes
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Query Parameters: To filter more precisely your request:

  • owner_org_id: (optional) (string, uuid) the organization id which is owner of the box. Default: the organization id making the request.
  • datatag_ids: (optional) (comma-separated list of strings, uuid) ids of datatag you want to retrieve. "" for boxes with no datatag. Default: all. Example: datatag_ids=7523588e-9c3d-4c9d-83b7-d98663bf1215,d9c01c3e-955a-4e98-b9f7-2610cc857108,"".
  • data_subject: (optional) (string) the subject value (identifier value - email). Default: all.
  • Pagination (more info). Default limit is 500.

Response#

Return an empty array if no boxes have been found.

HTTP 200 OK
[
{
"id": "7523588e-9c3d-4c9d-83b7-d98663bf1215",
"title": "Test Box",
"access_mode": "limited",
"datatag_id": "d9c01c3e-955a-4e98-b9f7-2610cc857108",
"data_subject": "data-subject@email.com",
"owner_org_id": "7dc50120-c840-4941-90cf-35c240646dd8",
"public_key": "anUnpaddedUrlSafeBase64",
"server_created_at": "2021-03-10T09:15:26.562703Z"
}
]

Messages#

Messages are the entity bearing data inside a box (which acts as a messages chat).

Send data as a text message#

Request#

POST https://api.misakey.com/boxes/:id/events
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id: (string, uuid) id of the box

JSON Body:

{
"type": "msg.text",
"content": {
"encrypted": "dGhpcyBpcyBhbiBlbmNvZGUgYmFzZTY0IHN0cmluZw=="
}
}
  • type: (string) must be msg.text
  • content:
    • encrypted: (string, unpadded url-safe base64) the encrypted message. Recall that files are sent separately in another way, so the size of a text message event should stay rather small.

Response#

HTTP 201 Created
{
"id": "f17169e0-61d8-4211-bb9f-bac29fe46d2d",
"type": "msg.text",
"box_id": "74ee16b5-89be-44f7-bcdd-117f496a90a7",
"server_event_created_at": "2038-11-05T00:00:00.000Z",
"sender": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
},
"content": {
"encrypted": "dGhpcyBpcyBhbiBlbmNvZGUgYmFzZTY0IHN0cmluZw=="
},
"referrer_id": null
}
  • id: (string, uuid) unique id the of message event
  • type: (string): msg.text
  • box_id: (string, uuid) id of the box
  • server_event_created_at: (date) server date creation
  • sender: (object) contains event sender information
  • content: (object) the content of the msg.text event
  • referrer_id: (string, nullable): will be null in this case

Send data as a message file#

The upload of an encrypted file triggers the creation of a msg.file event on the box then returns it.

Request#

POST https://api.misakey.com/boxes/:id/encrypted-files
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id (uuid string): the box unique id the file is uploaded in.
Encryption mecanism for files#

Incoming a description about how to consider encrypted_file & msg_encrypted_content...

Multipart Form Data Body:

  • encrypted_file (binary): the file, encrypted.
  • msg_encrypted_content (string, unpadded url-safe base64): encrypted content that will be store in the created msg.file event.

Response#

HTTP 201 Created

JSON Body:

{
"id": "cac1f19f-46eb-4be9-ba21-8346f1fd3838",
"type": "msg.file",
"content": {
"encrypted": "dGhpcyBpcyBhbiBlbmNvZGUgYmFzZTY0IHN0cmluZw==",
"public_key": "com.misakey.aes-rsa-enc:xZh9VyTJJyaGh8_92JQhKzpe0JiVLMLD0XdT4vHnJK48tl6a27cmhJMwpg7k9JITFiVa_Ahw3jergnRpRbhNRkp_Fhs8eaFtA3gUV2TPIhZCCGw86tk1d-XWWdGCZT4lbN3s8sCz9BYqXddg0UF4E5oT5JacBpJOrn13sYQL_KepMrgqrP3ddUPaLbXNhJJIR3rrLQyErtdpBm8sZvy8iAQ0EKDv7f0Qd1N7I1VNTG3baKYU3OUByfWEHJkcE4GACC52vCgpPM53GqCgcqF6DK1AiXzJLb4oE_WQ-XTgf9BUhzPEDtW3vu6G-Uifb5gqjRVUBlo99MzAAgHlMyVbX5010FGKphY09-vGKarpw8IRPbJLnD1qr4E4lwX6src3h6bwfxrJwwzvG-iuF1G4By3fyXU_Yd6O7u-bYy3POV6SrBhtQ5uBGmhRLWUuHhbF69Uq_eg7mNKdGz98R4t8pbYXCQfqy4Zgsv5SQ6wf69kVgSlB7zv4pB7LjklRKBmN",
"encrypted_file_id": "9b2c3cdc-d768-43ef-ba23-350b56b3d8ed"
},
"server_event_created_at": "2020-06-19T15:36:28.092359097Z",
"sender": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
},
"referrer_id": null
}
  • id: (string, uuid) unique id the of message event
  • type: (string): "msg.file"
  • box_id: (string, uuid) id of the box
  • server_event_created_at: (date) server date creation
  • sender: (object) contains event sender information
  • content:
    • encrypted: (binary) the encrypted data containing information about how to decrypt the file
    • public_key: (string): the box public key should have been used to encrypt the data
    • encrypted_file_id: (string, uuid) the generated unique id representing the file
  • referrer_id: (string, nullable): will be null in this case
info

Note that the msg.file object does not contain the file content but only information about how to retrieve the file and how to decrypt it:

  • encrypted_file_id should be used on Download a file route.
  • encrypted contains encrypted data itself containing information about how to decrypt the downloaded file. See here.

Notable Error Responses#

1 - The file is too big:

Code:

HTTP 400 BAD REQUEST
{
"code": "bad_request",
"origin": "not_defined",
"desc": "size: the maximum file size is 126MB.",
"details": {
"size": "invalid"
}
}
tip

If you need to upload file bigger than the current limit (126MB). Please contact us and we will certainly increase the limit or define a strategy together.

Count messages of a box#

You may want to count messages before listing them.

Request#

HEAD https://api.misakey.com/boxes/:id/messages

Query Parameters:

  • type (string) (optional) (one of: msg.text, msg.file): if you want to filter only text or file messages. Return all messages if not set.
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id (uuid string): the box id.

Response#

Code:

HTTP 204 No Content

Headers:

  • X-Total-Count (integer): the total count of messages.

List messages of a box#

The messages are returned from the latest message sent to the box to the oldest one.

GET https://api.misakey.com/boxes/:id/messages
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id (uuid string): the box id.

Query Parameters:

  • types (optional) (comma-separated list of string) (accepted values: msg.text, msg.file): if you want to filter for specific type of messages. Default: msg.text,msg.file.
  • Pagination (optional) (more info here). Default limit is 500.

Response#

Return an array of messages. An empty array is returned when no messages can be found.

Note that the content format may differ according to the type of message (see example below).

Code:

HTTP 200 OK

JSON Body:

[
{
"type": "msg.text",
"content": {
"encrypted": "hKpjaXBoZXJ0ZXh0xA9RY2JQ2gprmZNkwzfbd6ulbm9uY2XECDBWPnrsmVVAqGF1dGhfdGFnxCAUWchuBu9kTZn0ld45kl7-EuEm6sN78HKxc3wDjtpMlat3cmFwcGVkX2tlecUBgB-w9hzD3GWIsfawOeOOayJEedLx6i6pv5n5k_hJuCahj2IY6DaI9qWEJ-6kWXrX3lKiPUBjEkbBAXRVbtVSHNGYRvf_wD8JCd-KKTOdNyg-QqxOBYyFU1H6DepMMbh81ztVTRcoCjqmIr5blpkQY-MxWxwIeEy5IomL6q56w5p_elDxqe-kQT2mrZIaDI2Vf_8Uk2t4mz4qUIcnCIshVFTmyyF-RDXvRLBBMwtCZA_d-2G1o2c1bcwL93s2MqBhkM2FSm4zT7R1fK7rDR3CikbhGe_BaHnkB4-7CSnf_bGEhu3QPWHWIlc8koPf4tuRwUgyb0HDLk2kk3qhWtiD7AFj_TpcYgO7dVpaMXJTgXcso-JdtZBsG95FcYaa7p-4cEjfsak7UIrolyUfR2RV4ozXHZ-yyaFqqVTT_7IsKFdVpKOtpCGGBolYLU2m06-Xrz9_seRhbPUcV5wZBFPhrcBm8BCXjUGmn02lBX3ZsDSMKLZzPnwO1YCcxOVVljA2WQ",
"public_key": "com.misakey.aes-rsa-enc:4-byQXg9qk_h_wF7y37IiarpkrIw8tGuPdLmu35MI2vsCkgwaAiCPJNSNkRSEsjtRasPgJxS4BCKhaJ2cYMPLK8pg4x7UmsDws9JrjOY1QFyxnf_t2R0JEZUUsGnIgO0tTMBn34UDAkL1CwaKmQRyYv0DuNh4v63sOGRz-i_Qhhr77T7uV7ygzdQoSDQnt8KifNWUsk5di6wgG8bHjH6vD_m7W903i9fxDAk7XKSJTuooeG9nj4t2Re2hBMFRh85tRJohOFpCBXgvtqeq-ggxxrjHdS5qy0h7EFKqdd7Qi_JpB1uoXHMqRSYgG0v6Qh2M7_2BxueLC-igoK03qrr5o809lhwBM3pQw07CQ8tjyTd_Fg6bY2Najbs1amYNvrhLxZoXKEU0PxVnLTwo2BvSTMD3Xkz-QgafRaXh_VQxtr14ag_kc1op8BBOGWPYOpRQ4nY0HACXmOBywlVPMkTGbhnIqNpG3-FkcIAJXm4dlqqwBr6KK4tPnXf9lb0Sxw9"
},
"box_id": "e41f7d3e-928c-40dd-88c4-3fa69fdbd5ab",
"id": "aa59aebb-681d-48ab-8f09-83265bc5ff38",
"server_event_created_at": "2021-03-18T09:50:27.346555Z",
"referrer_id": null,
"sender": {
"id": "7825de94-a3d2-4484-8695-87854671e919",
"display_name": "C07221-Test",
"avatar_url": null,
"identifier_value": "c07221-test@misakey.com",
"identifier_kind": "email"
}
},
{
"type": "msg.file",
"content": {
"encrypted": "hKpjaXBoZXJ0ZXh0xO65Dho79eOMWLKq0JmOrV2tlaf4yiUnE3psT3vg1JWg2OQCh4jO0oE2u--13g4MVVwvqq5FPMVGuQGrQKoXTjtsxLHC_LY8C8QPReaACIMtLp2MTzwZCU41cEmW76_ICJA1LBD3DgCXQU5YCi6DoHwDd16cqEKYJGfO1dikeRUJSrpBARYDq99DnKMt5uPvBURWLEwu4CftAhkJKPu2lsWk3yFINAIlShTIJIyZ1qQ7AwX_ggynnp2TD0dyuENBSVuSOQAFtwBJiy8c92x6emXB39XgNKgD_T3izIPzADik1m_3pTVDC90WnE8E_ig_pW5vbmNlxAjVNFh3Qf2L5KhhdXRoX3RhZ8QgbnsnGMiuyKgUuVajJNkXO_zQohBgTAloGw6FVNgDlEyrd3JhcHBlZF9rZXnFAYBfESFdFFVtLVgrdzmvQAStedoFAa4uF9G2QAK2D_lcjGSMTYuFH1Tdz5ugdc90a_5Rp1jkZRuF4OcQXIRf2Wu3hpRIJQ8LEYoItaD_z9fn0Rp6yUAY8Rro9m1ukott4uiXzUzk0XnibPXZx1BVY3_Gm23UacHiV32NUPkgu3_xtEDX7IjDEILsHqjFybZIsFdJ-yEheeuzUPOIGjFuBLBgvFeYO9hZO7IHcr7ITW1AtXgL8rmOCRAGcCIu8ITOhSdwxR4_TakW6bWp8wk1y5-alzfLyW1KxB9J_XU1XsMadvRwy8kG_pxK8Jp1xhzrazQbQfhEOIW7V8WXDdRxzZlRNgivllXk41UQz86NmO4XLnMUXNNZpRHgKBwosD3oAmBbrSGKXHJX3ROWsb3tJuTTdnGz7M8U2gOM_YAREzhCvTvhrxRnrfgC8XM8wsRHux9m0VU9Dy0n9EsxAU-rhRe8TYQAWEbUu-dhEZIOTcNLW583hoWnLfZgHa0M8pwTR8c",
"public_key": "com.misakey.aes-rsa-enc:4-byQXg9qk_h_wF7y37IiarpkrIw8tGuPdLmu35MI2vsCkgwaAiCPJNSNkRSEsjtRasPgJxS4BCKhaJ2cYMPLK8pg4x7UmsDws9JrjOY1QFyxnf_t2R0JEZUUsGnIgO0tTMBn34UDAkL1CwaKmQRyYv0DuNh4v63sOGRz-i_Qhhr77T7uV7ygzdQoSDQnt8KifNWUsk5di6wgG8bHjH6vD_m7W903i9fxDAk7XKSJTuooeG9nj4t2Re2hBMFRh85tRJohOFpCBXgvtqeq-ggxxrjHdS5qy0h7EFKqdd7Qi_JpB1uoXHMqRSYgG0v6Qh2M7_2BxueLC-igoK03qrr5o809lhwBM3pQw07CQ8tjyTd_Fg6bY2Najbs1amYNvrhLxZoXKEU0PxVnLTwo2BvSTMD3Xkz-QgafRaXh_VQxtr14ag_kc1op8BBOGWPYOpRQ4nY0HACXmOBywlVPMkTGbhnIqNpG3-FkcIAJXm4dlqqwBr6KK4tPnXf9lb0Sxw9",
"encrypted_file_id": "ceba09a5-8ecb-49fb-ad7a-c268a98dfea1"
},
"box_id": "e41f7d3e-928c-40dd-88c4-3fa69fdbd5ab",
"id": "37d28a5d-6e26-4b99-89f1-fd1dfea1700d",
"server_event_created_at": "2021-03-18T09:50:27.312557Z",
"referrer_id": null,
"sender": {
"id": "7f67c7fb-2788-4747-8251-29cc72a4592c",
"display_name": "2da233-org",
"avatar_url": null,
"identifier_value": "", // empty when the identity creating the message is an org
"identifier_kind": "" // empty when the identity creating the message is an org
}
}
]
info

Note that the msg.file object does not contain the file content but only information about how to retrieve the file and how to decrypt it:

  • encrypted_file_id should be used on Download a file route.
  • encrypted contains encrypted data itself containing information about how to decrypt the downloaded file. See here.

Download an encrypted file#

Download an encrypted file as an octet-stream.

Request#

GET https://api.misakey.com/encrypted-files/:id
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id (string, uuid): the encrypted file id contained in the content of the msg.file event.

Response#

Code:

HTTP 200 OK

Headers:

  • Content-Type: application/octet-stream: the response is an octet stream.

Octect Stream Body:

(the raw data of the encrypted file)

Delete a message from a box#

A message (text or file) can be deleted by its author or by the box admin.

Request#

POST https://api.misakey.com/boxes/:id/events
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id (string, uuid): the box id.

JSON Body:

{
"type": "msg.delete",
"referrer_id": "f17169e0-61d8-4211-bb9f-bac29fe46d2d"
}
  • type: (string): should be msg.delete.
  • referrer_id: (string, uuid) the id of the message to delete.

Response#

HTTP 201 CREATED

JSON Body:

{
"type": "msg.delete",
"content": null, // no content for msg.delete events
"box_id": "87a63729-a6b2-4850-a229-35cfac9f9589",
"id": "41454af0-c732-4147-b0c3-87c063ada712",
"server_event_created_at": "2021-03-18T13:55:20.443076382Z",
"referrer_id": "288e5134-9329-4755-b5d6-2b550ede8286", // the id of the message that has been deleted
"sender": {
"id": "d181229c-30e1-4503-ad04-6b8e987a2462", // your org id
"display_name": "Your org display name",
"avatar_url": null,
"identifier_value": "",
"identifier_kind": ""
}
}

Box information#

Retrieve a box information#

A box can be retrieved using your organization token.

Request#

GET https://api.misakey.com/organizations/:oid/boxes/:id
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • oid (uuid string): your organization id.
  • id (uuid string): the box id wished to be retrieved.

Response#

Code:

HTTP 200 OK

JSON Body:

{
"id": "7523588e-9c3d-4c9d-83b7-d98663bf1215",
"title": "Test Box",
"access_mode": "limited",
"datatag_id": "d9c01c3e-955a-4e98-b9f7-2610cc857108",
"data_subject": "data-subject@email.com",
"owner_org_id": "7dc50120-c840-4941-90cf-35c240646dd8",
"public_key": "anUnpaddedUrlSafeBase64",
"server_created_at": "2021-03-10T09:15:26.562703Z"
}

Delete a box#

Only box admins are able to delete corresponding boxes.

A removed box sees its data completely removed from Misakey storage. This action is irreversible.

This action removes all data related to the box (events, files, key-shares...).

Request#

DELETE https://api.misakey.com/boxes/:id
Authorizations#
Headers:
  • Authorization: a bearer access token for your organization. Example: Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

Path Parameters:

  • id (string, uuid): the box id wished to be deleted.

JSON Body:

{
"user_confirmation": "delete"
}
  • user_confirmation (string) (one of: delete, supprimer): the input the end-identity has entered to confirm the deletion. The server will check if the value corresponds to some expected strings (cf one of).

Response#

Code:

HTTP 204 NO CONTENT