Skip to main content

Boxes

Introduction#

A box is a space where the end-identity can share securely the data with some other identity or themself.

It is the base for data exchange, data access management...

Boxes#

Creating a Box#

Request#

POST https://api.misakey.com/boxes

Cookies:

  • accesstoken (opaque token) (ACR >= 1): no identity check, just a valid token is required.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

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"
}
"invitation_data": {
"<public key>": "encrypted crypto action"
}
}
  • title is a free text required that is meant to describe the box purpose.
  • owner_org_id is an optional uuid corresponding to the organization owning the box (default is self org).
  • datatag_id is an optional uuid corresponding to a datatag representing the data type shipped through this box. owner_org_id must also bit set.
  • datatag_subject is an optional identifier to define the data subject of this box.
  • public_key and invitation_share_hash must be in unpadded url-safe base64. If the public key is for com.misakey.aes-rsa-enc algorithm, it must be prefixed with com.misakey.aes-rsa-enc:.
  • key_share is optional but will be soon mandatory. See box keys shares documentation about how to build it
  • invitation_data is optional but must be used if the datatag_subject has an account. It contains the encrypted crypto action to directly invite the user (see the extra field in the access events section)

When a box is created, it already contains a first event of type create that contains most of the information about the creation of the box.

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": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"server_created_at": "2020-06-12T13:38:32.142857839Z",
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"title": "Test Box",
"access_mode": "public",
"owner_org_id": "d1e9bfa6-e931-46b1-b73c-77cb3530aadb",
"creator": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
},
"last_event": {
"id": "ff6114f3-9838-40ed-a80d-bb376fd929f5",
"type": "create",
"content": {
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"title": "Test Box",
"state": "open"
},
"server_event_created_at": "2020-06-12T13:38:32.142857839Z",
"sender": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
}
}
}

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

Getting a Box#

Request#

GET https://api.misakey.com/boxes/:id

Cookies:

  • accesstoken (opaque token) (ACR >= 1): no identity check, just a valid token is required.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Path Parameters:

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

Response#

Code:

HTTP 200 OK

JSON Body:

{
"id": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"server_created_at": "2020-06-12T13:38:32.142857839Z",
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"title": "Test Box",
"access_mode": "limited",
"owner_org_id": "d1e9bfa6-e931-46b1-b73c-77cb3530aadb",
"creator": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
},
"events_count": 8, //if authenticated call
"settings": {
"identity_id": "ee4a5315-03f6-43ac-b40d-a9b2478587b9",
"box_id": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"muted": true
}, // if authenticated call
"last_event": {
"id": "ff6114f3-9838-40ed-a80d-bb376fd929f5",
"type": "create",
"content": {
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"title": "Test Box",
"state": "open"
},
"server_event_created_at": "2020-06-12T13:38:32.142857839Z",
"sender": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
}
}
}

Notable error reponses#

**I - The identity has no access to the box

The reason of the forbidden is explained is a reason field that have only 2 possible fixed values. Only the get box endpoint is ensured to return this error in the current state of the API.

HTTP 403 FORBIDDEN

JSON Body:

{
"code": "forbidden",
"origin": "not_defined",
"desc": "",
"details": {
"reason": "no_access|not_member"
}
}

Getting public info about a box#

This endpoint does not need any valid token, but it needs a valid invitation_share_hash corresponding to the box to get.

Request#

GET https://api.misakey.com/boxes/:id/public?invitation_share_hash=

Path Parameters:

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

Query Parameters:

  • invitation_share_hash (string) (unpadded url-safe base64): a hash of the other share.

Response#

Code:

HTTP 200 OK

JSON Body:

{
"title": "<title of the box>",
"owner_org_id": "<uuid representing the organization owning the box>",
"creator": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
}
}

Delete a box#

Moved here.

Reset the new events count for an identity#

The list of boxes return many information for each boxes, including a numerical field events_count telling how many event have occured since the connected identity's last visit.

This endpoint allows to reset the new events count of a box for a given identity.

It is a kind of an acknowledgement and it must be used when the identity want to mark the box as "read".

Request#

PUT https://api.misakey.com/boxes/:id/new-events-count/ack

Path Parameter:

  • id (string) (uuid): the box id to mark as "read"

JSON Body:

{
"identity_id": "e2e49259-f840-4991-a9f7-97c5f267bd18"
}

where identity_id is the identity of the requester who wants to acknowledge.

Cookies:

  • accesstoken (opaque token) (ACR >= 1): a valid access token corresponding to the identity of the body
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Response#

Code:

HTTP 204 NO CONTENT

Accesses#

Access defines who has access to a box considering some rules.

Add or remove accesses#

⚠️ Only box admins can add or remove accesses.

To add or remove accesses in a given box, please refer to:

Listing accesses for a given box#

Listing accesses allows admins to see the current state of the box reachability.

Request#

GET https://api.misakey.com/boxes/:id/accesses

Path Parameter:

  • id (string) (uuid): the box id to list accesses on.

Cookies:

  • accesstoken (opaque token) (ACR >= 2): the access token should belongs the a box admin.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Response#

Only the current valid accesses are returned.

[
{
"id": "f17169e0-61d8-4211-bb9f-bac29fe46d2d",
"type": "access.add",
"server_event_created_at": "2038-11-05T00:00:00.000Z",
"content": {
"restriction_type": "email_domain",
"value": "misakey.com"
}
},
{
"id": "f17169e0-61d8-4211-bb9f-bac29fe46d2d",
"type": "access.add",
"server_event_created_at": "2038-11-05T00:00:00.000Z",
"content": {
"restriction_type": "email",
"value": "sadin.nicolas7@gmail.com"
}
}
]

Membership#

Add or remove membership#

To add or remove membership for a couple <box, identity>, please refer to:

List boxes for the current identity#

Request#

Users are able to list boxes they have an access to.

The returned list is automatically computed from the server according to the authorization provided by the received bearer token.

GET https://api.misakey.com/boxes/joined

Cookies:

  • accesstoken (opaque token) (ACR >= 1): a valid token.
  • tokentype: must be bearer.

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Query Parameters:

  • owner_org_id (uuid) (default: hosting-org): the organization id owning the box.
  • datatag_id (optional) (uuid): the datatag id corresponding to the data type. "" for boxes with no datatag. Empty parameter for all boxes.
  • 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,"".
  • Pagination (more info) with default limit set to 10.

Response#

Code:

HTTP 200 OK

A list of event is returned.

[
{
"id": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"server_created_at": "2020-06-12T13:38:32.142857839Z",
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"title": "Test Box",
"access_mode": "limited",
"owner_org_id": "d1e9bfa6-e931-46b1-b73c-77cb3530aadb",
"creator": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
},
"events_count": 8, //if authenticated call
"settings": {
"identity_id": "ee4a5315-03f6-43ac-b40d-a9b2478587b9",
"box_id": "91ec8274-2b6d-40ff-afad-83e8ba5808e5",
"muted": true
}, // if authenticated call
"last_event": {
"id": "ff6114f3-9838-40ed-a80d-bb376fd929f5",
"type": "create",
"content": {
"public_key": "ShouldBeUnpaddedUrlSafeBase64",
"title": "Test Box",
"state": "open"
},
"server_event_created_at": "2020-06-12T13:38:32.142857839Z",
"sender": {
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
}
}
}
]

Count boxes for the current identity#

Request#

This request allows to retrieval of information about accessible boxes list.

Today only the total count of boxes is returned as an response header.

HEAD https://api.misakey.com/boxes/joined?owner_org_id=d1e9bfa6-e931-46b1-b73c-77cb3530aadb

Cookies:

  • accesstoken (opaque token) (ACR >= 1): a valid token.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Query Parameters:

  • owner_org_id (uuid) (default: hosting-org): the organization id owning the box.
  • datatag_id (uuid): the datatag id corresponding to the data type. "" for boxes with no datatag. Empty parameter for all boxes.
  • 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,"".

Response#

Code:

HTTP 204 NO CONTENT

Headers:

  • X-Total-Count (integer): the total count of boxes that the identity can access.

Listing active members of a box#

This endpoint return all identities that have an active membership to the box.

Identities who have left and have been kicked out of the box are not returned.

Request#

GET https://api.misakey.com/boxes/:id/members

Path Parameter:

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

Cookies:

  • accesstoken (opaque token) (ACR >= 1): a valid token.
  • tokentype: must be bearer

Headers:

  • X-CSRF-Token: a token to prevent from CSRF attacks.

Response#

Code:

HTTP 200 OK

A list of senders is returned.

[
{
"id": "fcfacf74-b15e-4583-bb71-55eb42cf2758",
"display_name": "Jean-Michel User",
"avatar_url": null,
"identifier_value": "jean-michel@misakey.com",
"identifier_kind": "email"
}
]