Sharing¶



The owner of a cozy instance can share access to her documents to other users.

A client-side application can propose sharing by links:

The application must have a public route in its manifest. See Apps documentation for how to do that.
The application can create a set of permissions for the shared documents, with codes. Another code called shortcode is also generated and associated with the code. This shortcode is much smaller (but secure), which is easier to be shared. See permissions documentation for the details.
The application can then create a shareable link (e.g. https://calendar.cozy.example.net/public?sharecode=eiJ3iepoaihohz1Y) by putting together the app sub-domain, the public route path, and a code for the permissions set.
The app can then send this link by mail, via the jobs system, or just give it to the user, so he can transmit it to her friends via chat or other ways.

When someone opens the shared link, the stack will load the public route, find the corresponding index.html file, and replace {{.Token}} inside it by a token with the same set of permissions that sharecode offers. This token can then be used as a Bearer token in the Authorization header for requests to the stack (or via cozy-client-js).

NB: The shortcode can also be used as the Bearer. In this case, the corresponding sharecode will be matched on server-side

If necessary, the application can list the permissions for the token by calling /permissions/self with this token.

The owner of a cozy instance can send and synchronize documents to others cozy users.

Intents¶

When a sharing is authorized, the user is redirected to their cozy on the application that was used for the sharing (when possible). It’s possible to use a specific route to do so, via the intents. The application must declare an intent in its manifest for the action SHARING. The doctype of the intent must be the same as the doctype of the first rule of the sharing. In the redirect URL, the query string will have a sharing parameter with the sharing ID (but no intent parameter).

Routes¶

POST /sharings/¶

Create a new sharing. The sharing rules and recipients must be specified. The description, preview_path, and open_sharing fields are optional. The app_slug field is optional and is the slug of the web app by default.

See the doc on io.cozy.sharings for in-depth explanation of all attributes.

To create a sharing, no permissions on io.cozy.sharings are needed: an application can create a sharing on the documents for whose it has a permission.

Request¶

POST /sharings/ HTTP/1.1
Host: alice.example.net
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "attributes": {
      "description": "sharing test",
      "preview_path": "/preview-sharing",
      "rules": [
        {
          "title": "Hawaii",
          "doctype": "io.cozy.files",
          "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
          "add": "sync",
          "update": "sync",
          "remove": "sync"
        }
      ]
    },
    "relationships": {
      "recipients": {
        "data": [
          {
            "id": "2a31ce0128b5f89e40fd90da3f014087",
            "type": "io.cozy.contacts"
          },
          {
            "id": "51bbc980acb0013cb5f618c04daba326",
            "type": "io.cozy.contacts.groups"
          }
        ]
      }
    }
  }
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "meta": {
      "rev": "1-4859c6c755143adf0838d225c5e97882"
    },
    "attributes": {
      "description": "sharing test",
      "preview_path": "/preview-sharing",
      "app_slug": "drive",
      "owner": true,
      "created_at": "2018-01-04T12:35:08Z",
      "updated_at": "2018-01-04T13:45:43Z",
      "members": [
        {
          "status": "owner",
          "public_name": "Alice",
          "email": "alice@example.net",
          "instance": "alice.example.net"
        },
        {
          "status": "mail-not-sent",
          "name": "Bob",
          "email": "bob@example.net"
        },
        {
          "status": "mail-not-sent",
          "name": "Gaby",
          "email": "gaby@example.net",
          "only_in_groups": true,
          "groups": [0]
        }
      ],
      "groups": [
        {
          "id": "51bbc980acb0013cb5f618c04daba326",
          "name": "G. people",
          "addedBy": 0
        }
      ],
      "rules": [
        {
          "title": "Hawaii",
          "doctype": "io.cozy.files",
          "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
          "add": "sync",
          "update": "sync",
          "remove": "sync"
        }
      ]
    },
    "links": {
      "self": "/sharings/ce8835a061d0ef68947afe69a0046722"
    }
  }
}

GET /sharings/:sharing-id/discovery¶

If no preview_path is set, it’s an URL to this route that will be sent to the users to notify them that someone wants to share something with them. On this page, they can fill the URL of their Cozy (if the user has already filled its Cozy URL in a previous sharing, the form will be pre-filled and the user will just have to click OK).

Query-String¶

Parameter	Description
state	a code that identify the recipient

Example¶

GET /sharings/ce8835a061d0ef68947afe69a0046722/discovery?state=eiJ3iepoaihohz1Y HTTP/1.1
Host: alice.example.net

POST /sharings/:sharing-id/discovery¶

Give to the cozy of the sharer the URL of the Cozy of one recipient. The sharer will register its-self as an OAuth client on the recipient cozy, and then will ask the recipient to accept the permissions on its instance.

This route exists in two versions, the version is selected by the HTTP header Accept

Classical (`x-www-form-urlencoded`)¶

Parameter	Description
state	a code that identify the recipient
url	the URL of the Cozy for the recipient

Example¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/discovery HTTP/1.1
Host: alice.example.org
Content-Type: application/x-www-form-urlencoded
Accept: text/html

state=eiJ3iepoaihohz1Y&url=https://bob.example.net/

HTTP/1.1 302 Moved Temporarily
Location: https://bob.example.net/auth/sharing?...

JSON¶

This version can be more convenient for applications that implement the preview page. To do that, an application must give a preview_path when creating the sharing. This path must be a public route of this application. The recipients will receive a link to the application subdomain, on this page, and with a sharecode in the query string (like for a share by link).

To know the sharing-id, it’s possible to ask GET /permissions/self, with the sharecode in the Authorization header (it’s a JWT token). In the response, the source_id field will be io.cozy.sharings/<sharing-id>.

Parameters¶

Parameter	Description
sharecode	a code that identify the recipient
url	the URL of the Cozy for the recipient

Example¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/discovery HTTP/1.1
Host: alice.example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

sharecode=eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJhcHAiLCJpYXQiOjE1MjAzNDM4NTc&url=https://bob.example.net/

HTTP/1.1 200 OK
Content-Type: application/json

{
  "redirect": "https://bob.example.net/auth/sharing?..."
}

POST /sharings/:sharing-id/preview-url¶

This internal route can be used by the stack to get the URL where a member can preview the sharing.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/discovery-url HTTP/1.1
Host: alice.example.net
Content-Type: application/json

{
  "state": "eiJ3iepoaihohz1Y"
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "url": "https://drive.alice.example.net/preview?sharecode=..."
}

GET /sharings/:sharing-id¶

Get the information about a sharing. This includes the content of the rules, the members, as well as the already shared documents for this sharing.

For a member, we can have the following fields:

a contact name (name), that is the name of this user as it appears in its contact document (if there is one such document)
a public name (public_name), that is the name this user has put on his cozy as a public name (it is used for sending emails for example)
an email addresse (email)
an instance URL (instance)
and a status (status).

Notes:

the first member is always the sharer
to display the list of members to a user, the name should be use if available, and if it is not the case, you can use the public_name or the email
on a recipient, the only member with an instance is the local user.

Request¶

GET /sharings/ce8835a061d0ef68947afe69a0046722 HTTP/1.1
Host: alice.example.net
Accept: application/vnd.api+json

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "meta": {
      "rev": "1-4859c6c755143adf0838d225c5e97882"
    },
    "attributes": {
      "description": "sharing test",
      "preview_path": "/preview-sharing",
      "app_slug": "drive",
      "owner": true,
      "created_at": "2018-01-04T12:35:08Z",
      "updated_at": "2018-01-04T13:45:43Z",
      "initial_number_of_files_to_sync": 42,
      "members": [
        {
          "status": "owner",
          "public_name": "Alice",
          "email": "alice@example.net",
          "instance": "alice.example.net"
        },
        {
          "status": "ready",
          "name": "Bob",
          "email": "bob@example.net"
        }
      ],
      "rules": [
        {
          "title": "Hawaii",
          "doctype": "io.cozy.files",
          "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
          "add": "sync",
          "update": "sync",
          "remove": "sync"
        }
      ]
    },
    "relationships": {
      "shared_docs": {
        "data": [
          {
            "id": "612acf1c-1d72-11e8-b043-ef239d3074dd",
            "type": "io.cozy.files"
          },
          {
            "id": "a34528d2-13fb-9482-8d20-bf1972531225",
            "type": "io.cozy.files"
          }
        ]
      }
    },
    "links": {
      "self": "/sharings/ce8835a061d0ef68947afe69a0046722"
    }
  }
}

GET /sharings/news¶

It returns the number of shortcuts to a sharing that have not been seen.

Request¶

GET /sharings/news HTTP/1.1
Host: alice.example.net
Accept: application/vnd.api+json

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "meta": {
    "count": 5
  }
}

GET /sharings/doctype/:doctype¶

Get information about all the sharings that have a rule for the given doctype. This includes the content of the rules, the members, as well as the already shared documents for this sharing.

Request¶

GET /sharings/doctype/io.cozy.files HTTP/1.1
Host: alice.example.net
Accept: application/vnd.api+json

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "type": "io.cozy.sharings",
      "id": "ce8835a061d0ef68947afe69a0046722",
      "attributes": {
        "description": "sharing test",
        "preview_path": "/preview-sharing",
        "app_slug": "drive",
        "owner": true,
        "created_at": "2018-01-04T12:35:08Z",
        "updated_at": "2018-01-04T13:45:43Z",
        "members": [
          {
            "status": "owner",
            "public_name": "Alice",
            "email": "alice@example.net",
            "instance": "alice.example.net"
          },
          {
            "status": "ready",
            "name": "Bob",
            "email": "bob@example.net"
          }
        ],
        "rules": [
          {
            "title": "Hawaii",
            "doctype": "io.cozy.files",
            "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
            "add": "sync",
            "update": "sync",
            "remove": "sync"
          }
        ]
      },
      "meta": {
        "rev": "1-4859c6c755143adf0838d225c5e97882"
      },
      "links": {
        "self": "/sharings/ce8835a061d0ef68947afe69a0046722"
      },
      "relationships": {
        "shared_docs": {
          "data": [
            {
              "id": "612acf1c-1d72-11e8-b043-ef239d3074dd",
              "type": "io.cozy.files"
            },
            {
              "id": "a34528d2-13fb-9482-8d20-bf1972531225",
              "type": "io.cozy.files"
            }
          ]
        }
      }
    },
    {
      "type": "io.cozy.sharings",
      "id": "b4e58d039c03d01742085de5e505284e",
      "attributes": {
        "description": "another sharing test",
        "preview_path": "/preview-sharing",
        "app_slug": "drive",
        "owner": true,
        "created_at": "2018-02-04T12:35:08Z",
        "updated_at": "2018-02-04T13:45:43Z",
        "members": [
          {
            "status": "owner",
            "public_name": "Alice",
            "email": "alice@example.net",
            "instance": "alice.example.net"
          },
          {
            "status": "ready",
            "name": "Bob",
            "email": "bob@example.net"
          }
        ],
        "rules": [
          {
            "title": "Singapore",
            "doctype": "io.cozy.files",
            "values": ["e18e30e2-8eda-1bde-afce-edafc6b1a91b"],
            "add": "sync",
            "update": "sync",
            "remove": "sync"
          }
        ]
      },
      "meta": {
        "rev": "1-7ac5f1252a0c513186a5d35b1a6fd350"
      },
      "links": {
        "self": "/sharings/b4e58d039c03d01742085de5e505284e"
      },
      "relationships": {
        "shared_docs": {
          "data": [
            {
              "id": "dcc52bee-1277-a6b3-b36f-369ffd81a4ee",
              "type": "io.cozy.files"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "count": 3
  }
}

PUT /sharings/:sharing-id¶

The sharer’s cozy sends a request to this route on the recipient’s cozy to create a sharing request, with information about the sharing. This request can be used for two scenarios:

This request will be displayed to the recipient just before its final acceptation of the sharing, to be sure they know what will be shared.
This request will be used to create a shortcut (in that case, a query-string parameter shortcut=true&url=... will be added).

Request¶

PUT /sharings/ce8835a061d0ef68947afe69a0046722 HTTP/1.1
Host: bob.example.net
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "attributes": {
      "description": "sharing test",
      "preview_path": "/preview-sharing",
      "app_slug": "drive",
      "owner": true,
      "created_at": "2018-01-04T12:35:08Z",
      "updated_at": "2018-01-04T13:45:43Z",
      "members": [
        {
          "status": "owner",
          "public_name": "Alice",
          "email": "alice@example.net",
          "instance": "alice.example.net"
        },
        {
          "status": "mail-not-sent",
          "email": "bob@example.net",
          "instance": "bob.example.net"
        }
      ],
      "rules": [
        {
          "title": "Hawaii",
          "doctype": "io.cozy.files",
          "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
          "add": "sync",
          "update": "sync",
          "remove": "sync"
        }
      ]
    }
  }
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "meta": {
      "rev": "1-f579a69a9fa5dd720010a1dbb82320be"
    },
    "attributes": {
      "description": "sharing test",
      "preview_path": "/preview-sharing",
      "app_slug": "drive",
      "owner": true,
      "created_at": "2018-01-04T12:35:08Z",
      "updated_at": "2018-01-04T13:45:43Z",
      "members": [
        {
          "status": "owner",
          "public_name": "Alice",
          "email": "alice@example.net",
          "instance": "alice.example.net"
        },
        {
          "status": "mail-not-sent",
          "name": "Bob",
          "email": "bob@example.net",
          "instance": "bob.example.net"
        }
      ],
      "rules": [
        {
          "title": "Hawaii",
          "doctype": "io.cozy.files",
          "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
          "add": "sync",
          "update": "sync",
          "remove": "sync"
        }
      ]
    },
    "links": {
      "self": "/sharings/ce8835a061d0ef68947afe69a0046722"
    }
  }
}

POST /sharings/:sharing-id/answer¶

This route is used by the Cozy of a recipient to exchange credentials with the Cozy of the sharer, after the recipient has accepted a sharing.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/answer HTTP/1.1
Host: alice.example.net
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings.answer",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "attributes": {
      "public_name": "Bob",
      "state": "eiJ3iepoaihohz1Y",
      "client": {...},
      "access_token": {...}
    }
  }
}

When the sharing has a rule for bitwarden organization, the attributes also have a bitwarden object with user_id and public_key, to make it possible to share documents end to end encrypted.

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings.answer",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "attributes": {
      "client": {...},
      "access_token": {...}
    }
  }
}

POST /sharings/:sharing-id/public-key¶

This route can be used by a sharing member to send their new public key after they have chosen their password for the first time (delegated authentication).

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/public-key HTTP/1.1
Host: alice.example.net
Content-Type: application/vnd.api+json
Authorization: Bearer ...

{
  "data": {
    "type": "io.cozy.sharings.answer",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "attributes": {
      "bitwarden": {
        "user_id": "0dc76ad9b1cf3a979b916b3155001830",
        "public_key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA1wboB9QutvRKGswphAre6xi4boYxSw4IjXqXDTV297Cq/MB2cBklj+sMmRQNTkU266HFSTGp3jDVcegAsHMpVVlTKZnWW+gSP2+vSyGs9NUvG8JfLday1iuOntHJQkfYiZ7+BfBYFtx6iWRnbnegickyoS7PWibLP5lmEzZnFtrGcRT8urSfN61qlOVD1u+eqtif5tabdU6eyNWUMLCQYgtaGb1nNht/xDgbpBc3b2XbEF0tBJRFR5571EH1h//Ae7IT+pYuBZB9BoPAHj4fhQm3++oNjemUJbaVi0dM4KNfQ89z1lBBCh5lxAGPlpOjapN0qGPgSov8B9U+qXlmzQIDAQAB"
      }
    }
  }
}

Response¶

HTTP/1.1 204 No Content

POST /sharings/:sharing-id/recipients¶

This route allows the sharer to add new recipients (and groups of recipients) to a sharing. It can also be used by a recipient when the sharing has open_sharing set to true if the recipient doesn’t have the read_only flag.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/recipients HTTP/1.1
Host: alice.example.net
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "relationships": {
      "recipients": {
        "data": [
          {
            "id": "ce7b1dfbd460039159f228298a29b2aa",
            "type": "io.cozy.contacts"
          }
        ]
      },
      "read_only_recipients": {
        "data": [
          {
            "id": "e15384a1223ae2501cc1c4fa94008ea0",
            "type": "io.cozy.contacts"
          }
        ]
      }
    }
  }
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "meta": {
      "rev": "1-4859c6c755143adf0838d225c5e97882"
    },
    "attributes": {
      "description": "sharing test",
      "preview_path": "/preview-sharing",
      "app_slug": "drive",
      "owner": true,
      "created_at": "2018-01-04T12:35:08Z",
      "updated_at": "2018-01-04T13:45:43Z",
      "members": [
        {
          "status": "owner",
          "public_name": "Alice",
          "email": "alice@example.net",
          "instance": "alice.example.net"
        },
        {
          "status": "ready",
          "name": "Bob",
          "public_name": "Bob",
          "email": "bob@example.net"
        },
        {
          "status": "pending",
          "name": "Charlie",
          "email": "charlie@example.net"
        },
        {
          "status": "pending",
          "name": "Dave",
          "email": "dave@example.net",
          "read_only": true
        }
      ],
      "rules": [
        {
          "title": "Hawaii",
          "doctype": "io.cozy.files",
          "values": ["612acf1c-1d72-11e8-b043-ef239d3074dd"],
          "add": "sync",
          "update": "sync",
          "remove": "sync"
        }
      ]
    },
    "relationships": {
      "shared_docs": {
        "data": [
          {
            "id": "612acf1c-1d72-11e8-b043-ef239d3074dd",
            "type": "io.cozy.files"
          },
          {
            "id": "a34528d2-13fb-9482-8d20-bf1972531225",
            "type": "io.cozy.files"
          }
        ]
      }
    },
    "links": {
      "self": "/sharings/ce8835a061d0ef68947afe69a0046722"
    }
  }
}

POST /sharings/:sharing-id/recipients/delegated¶

This is an internal route for the stack. It is called by the recipient cozy on the owner cozy to add recipients and groups to the sharing (open_sharing: true only). Data for direct recipients should contain an email address but if it is not known, an instance URL can also be provided.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/recipients/delegated HTTP/1.1
Host: alice.example.net
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "relationships": {
      "recipients": {
        "data": [
          {
            "email": "dave@example.net"
          }
        ]
      },
      "groups": {
        "data": [
          {
            "id": "b57cd790b2f4013c3ced18c04daba326",
            "name": "Dance",
            "addedBy": 1
          }
        ]
      }
    }
  }
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "dave@example.net": "uS6wN7fTYaLZ-GdC_P6UWA"
}

POST /sharings/:sharing-id/members/:index/invitation¶

This is an internal route for the stack. It is called by the recipient cozy on the owner cozy to send an invitation.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/members/4/invitation HTTP/1.1
Host: alice.example.net
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings.members",
    "attributes": {
      "email": "diana@example.net"
    }
  }
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "diana@example.net": "uS6wN7fTYaLZ-GdC_P6UWA"
}

DELETE /sharings/:sharing-id/groups/:group-index/:member-index¶

This is an internal route for the stack. It is called by the recipient cozy on the owner cozy to remove a member of a sharing from a group.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/groups/0/1 HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

PUT /sharings/:sharing-id/recipients¶

This internal route is used to update the list of members (their states, emails and names) and the list of groups on the recipients cozy. The token used for this route can be the access token for a sharing where synchronization is active, or the sharecode for a member who has only a shortcut to the sharing on their Cozy instance.

Request¶

PUT /sharings/ce8835a061d0ef68947afe69a0046722/recipients HTTP/1.1
Host: bob.example.net
Content-Type: application/vnd.api+json

{
  "data": [
    {
      "status": "owner",
      "public_name": "Alice",
      "email": "alice@example.net",
      "instance": "alice.example.net"
    },
    {
      "status": "ready",
      "name": "Bob",
      "public_name": "Bob",
      "email": "bob@example.net"
    },
    {
      "status": "ready",
      "name": "Charlie",
      "public_name": "Charlie",
      "email": "charlie@example.net"
    },
    {
      "status": "pending",
      "name": "Dave",
      "email": "dave@example.net",
      "read_only": true
    }
  ],
  "included": [
    {
      "id": "51bbc980acb0013cb5f618c04daba326",
      "name": "G. people",
      "addedBy": 0
    }
  ]
}

Response¶

HTTP/1.1 204 No Content

GET /sharings/:sharing-id/recipients/:index/avatar¶

This route can be used to get an image that shows the avatar of a member of this sharing. No permission is required to use this route, you just need to know the sharing-id to use it. If no image has been chosen, a fallback will be used, depending of the fallback parameter in the query-string:

initials: a generated image with the initials of the owner’s public name. This is the default behavior.
404: just a 404 - Not found error.

If the initials fallback is used and the member has not yet seen the sharing, the background of the image will be grey.

Note: 0 for the index means the sharer.

Request¶

GET /sharings/ce8835a061d0ef68947afe69a0046722/recipients/2/avatar HTTP/1.1
Host: bob.example.net
Accept: image/*

POST /sharings/:sharing-id/recipients/:index/readonly¶

This route is used to add the read-only flag on a recipient of a sharing.

Note: 0 is not accepted for index, as it is the sharer him-self.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/recipients/3/readonly HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

POST /sharings/:sharing-id/recipients/self/readonly¶

This is an internal route for the stack. It’s used to inform the recipient’s cozy that it is no longer in read-write mode. It also gives it an access token with a short validity (1 hour) to let it try to synchronize its last changes before going to read-only mode.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/recipients/self/readonly HTTP/1.1
Host: bob.example.net
Authorization: Bearer ...
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings.answer",
    "id": "4dadbcae3f2d7a982e1b308eea000751",
    "attributes": {
      "client": {...},
      "access_token": {...}
    }
  }
}

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/recipients/:index/readonly¶

This route is used to remove the read-only flag on a recipient of a sharing.

Note: 0 is not accepted for index, as it is the sharer him-self.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/recipients/3/readonly HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/recipients/self/readonly¶

This is an internal route for the stack. It’s used to inform the recipient’s cozy that it is no longer in read-only mode, and to give it the credentials for sending its updates.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/recipients/self/readonly HTTP/1.1
Host: bob.example.net
Authorization: Bearer ...
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings.answer",
    "id": "4dadbcae3f2d7a982e1b308eea000751",
    "attributes": {
      "client": {...},
      "access_token": {...}
    }
  }
}

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/recipients¶

This route is used by an application on the owner’s cozy to revoke the sharing for all the members. After that, the sharing active flag will be false, the credentials for all members will be revoked, the members that have accepted the sharing will have their cozy informed that the sharing has been revoked, and pending members can no longer accept this sharing.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/recipients HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/recipients/:index¶

This route can be only be called on the cozy instance of the sharer to revoke only one recipient of the sharing. The parameter is the index of this recipient in the members array of the sharing. The status for this member will be set to revoked, its cozy will be informed of the revokation, and the credentials for this cozy will be deleted.

Note: 0 is not accepted for index, as it is the sharer him-self.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/recipients/1 HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/groups/:index¶

This route can be only be called on the cozy instance of the sharer to revoke a group of the sharing. The parameter is the index of this recipient in the groups array of the sharing. The removed property for this group will be set to true, and it will revoke the members of this group unless they are still part of the sharing via another group or as direct recipients.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/groups/0 HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/recipients/self¶

This route can be used by an application in the cozy of a recipient to remove it from the sharing.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/recipients/self HTTP/1.1
Host: bob.example.net

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id¶

This is an internal route used by the cozy of the sharing’s owner to inform a recipient’s cozy that it was revoked.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722 HTTP/1.1
Host: bob.example.net

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/answer¶

This is an internal route used by a recipient’s cozy to inform the owner’s cozy that this recipient no longer wants to be part of the sharing.

Request¶

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/answer HTTP/1.1
Host: alice.example.net

Response¶

HTTP/1.1 204 No Content

POST /sharings/:sharing-id/recipients/self/moved¶

This route can be used to inform that a Cozy has been moved to a new address.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/recipients/self/moved HTTP/1.1
Host: bob.example.net
Authorization: Bearer ...
Content-Type: application/vnd.api+json

{
  "data": {
    "type": "io.cozy.sharings.moved",
    "id": "ce8835a061d0ef68947afe69a0046722",
    "attributes": {
      "new_instance": "https://alice.newcozy.example",
      "access_token": "xxx",
      "refresh_token": "xxx"
    }
  }
}

Response¶

HTTP/1.1 204 No Content

POST /sharings/:sharing-id/_revs_diff¶

This endpoint is used by the sharing replicator of the stack to know which documents must be sent to the other cozy. It is inspired by http://docs.couchdb.org/en/stable/api/database/misc.html#db-revs-diff.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/_revs_diff HTTP/1.1
Host: bob.example.net
Accept: application/json
Content-Type: application/json
Authorization: Bearer ...

{
  "io.cozy.files/29631902-2cec-11e8-860d-435b24c2cc58": [
    "2-4a7e4ae49c4366eaed8edeaea8f784ad"
  ],
  "io.cozy.files/44f5752a-2cec-11e8-b227-abfc3cfd4b6e": [
    "4-2ee767305024673cfb3f5af037cd2729",
    "4-efc54218773c6acd910e2e97fea2a608"
  ]
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "io.cozy.files/44f5752a-2cec-11e8-b227-abfc3cfd4b6e": {
    "missing": ["4-2ee767305024673cfb3f5af037cd2729"],
    "possible_ancestors": ["3-753875d51501a6b1883a9d62b4d33f91"]
  }
}

POST /sharings/:sharing-id/_bulk_docs¶

This endpoint is used by the sharing replicator of the stack to send documents in a bulk to the other cozy. It is inspired by http://docs.couchdb.org/en/stable/api/database/bulk-api.html#db-bulk-docs.

Note: we force new_edits to false.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/_bulk_docs HTTP/1.1
Host: bob.example.net
Accept: application/json
Content-Type: application/json
Authorization: Bearer ...

{
  "io.cozy.files": [
    {
      "_id": "44f5752a-2cec-11e8-b227-abfc3cfd4b6e",
      "_rev": "4-2ee767305024673cfb3f5af037cd2729",
      "_revisions": {
        "start": 4,
        "ids": [
          "2ee767305024673cfb3f5af037cd2729",
          "753875d51501a6b1883a9d62b4d33f91"
        ]
      }
    }
  ]
}

Response¶

HTTP/1.1 200 OK
Content-Type: application/json

[]

GET /sharings/:sharing-id/io.cozy.files/:file-id¶

This is an internal endpoint used by a stack to get information about a folder. It is used when a cozy sent to another cozy a file or folder inside a folder that was trashed (and trash was emptied): the recipient does no longer have information about the parent directory. To resolve the conflict, it recreates the missing parent directory by asking the other cozy informations about it.

Request¶

GET /sharings/ce8835a061d0ef68947afe69a0046722/io.cozy.files/6d245d072be5522bd3a6f273dd000c65 HTTP/1.1
Host: alice.example.net
Accept: application/json
Authorization: Bearer ...

Response¶

HTTP/1.1 200 OK
Content-Type: application/json

{
  "_id": "6d245d072be5522bd3a6f273dd000c65",
  "_rev": "1-de4ec176ffa9ddafe8bdcc739dc60fed",
  "type": "directory",
  "name": "phone",
  "dir_id": "6d245d072be5522bd3a6f273dd007396",
  "created_at": "2016-09-19T12:35:08Z",
  "updated_at": "2016-09-19T12:35:08Z",
  "tags": ["bills"]
}

PUT /sharings/:sharing-id/io.cozy.files/:file-id/metadata¶

This is an internal endpoint used by a stack to send the new metadata about a file that has changed.

Request¶

PUT /sharings/ce8835a061d0ef68947afe69a0046722/io.cozy.files/0c1116b028c6ae6f5cdafb949c088265/metadata HTTP/1.1
Host: bob.example.net
Accept: application/json
Content-Type: application/json
Authorization: Bearer ...

{
  "_id": "4b24ab130b2538b7b444fc65430198ad",
  "_rev": "1-356bf77c03baa1da851a2be1f06aba81",
  "_revisions": {
    "start": 1,
    "ids": ["356bf77c03baa1da851a2be1f06aba81"]
  },
  "type": "file",
  "name": "cloudy.jpg",
  "dir_id": "4b24ab130b2538b7b444fc65430188cd",
  "created_at": "2018-01-03T16:10:36.885807013+01:00",
  "updated_at": "2018-01-03T16:10:36.885807013+01:00",
  "size": "84980",
  "md5sum": "SuRJOiD/QPwDUpKpQujcVA==",
  "mime": "image/jpeg",
  "class": "image",
  "executable": false,
  "trashed": false,
  "tags": [],
  "metadata": {
    "datetime": "2018-01-03T16:10:36.89118949+01:00",
    "extractor_version": 2,
    "height": 1200,
    "width": 1600
  }
}

Response¶

If only the metadata has changed (not the content), the response will be a 204:

HTTP/1.1 204 No Content

Else, the content will need to be uploaded:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "key": "dcd478c6-46cf-11e8-9c3f-535468cbce7b"
}

PUT /sharings/:sharing-id/io.cozy.files/:key¶

Upload the content of a file (new file or its content has changed since the last synchronization).

Request¶

PUT /sharings/ce8835a061d0ef68947afe69a0046722/io.cozy.files/dcd478c6-46cf-11e8-9c3f-535468cbce7b HTTP/1.1
Host: bob.example.net
Content-Type: image/jpeg
Authorization: Bearer ...

Response¶

HTTP/1.1 204 No Content

POST /sharings/:sharing-id/reupload¶

This is an internal route for the stack. It is called when the disk quota of an instance is increased to ask for the others instances on this sharing to try to reupload files without waiting for the normal retry period.

Request¶

POST /sharings/ce8835a061d0ef68947afe69a0046722/reupload HTTP/1.1
Host: bob.example.net
Authorization: Bearer ...

Response¶

HTTP/1.1 204 No Content

DELETE /sharings/:sharing-id/initial¶

This internal route is used by the sharer to inform a recipient’s cozy that the initial sync is finished.

DELETE /sharings/ce8835a061d0ef68947afe69a0046722/initial HTTP/1.1
Host: bob.example.net
Authorization: Bearer ...

Response¶

HTTP/1.1 204 No Content

Real-time via websockets¶

You can subscribe to the realtime API for the normal doctypes, but also for a special io.cozy.sharings.initial_sync doctype. For this doctype, you can give the id of a sharing and you will be notified when a file will be received during the initial synchronisation (UPDATED), and when the sync will be done (DELETED).

Example¶

client > {"method": "AUTH",
          "payload": "xxAppOrAuthTokenxx="}
client > {"method": "SUBSCRIBE",
          "payload": {"type": "io.cozy.sharings.initial_sync", "id": "ce8835a061d0ef68947afe69a0046722"}}
server > {"event": "UPDATED",
          "payload": {"id": "ce8835a061d0ef68947afe69a0046722", "type": "io.cozy.sharings.initial_sync", "doc": {"count": 12}}}
server > {"event": "UPDATED",
          "payload": {"id": "ce8835a061d0ef68947afe69a0046722", "type": "io.cozy.sharings.initial_sync", "doc": {"count": 13}}}
server > {"event": "DELETED",
          "payload": {"id": "ce8835a061d0ef68947afe69a0046722", "type": "io.cozy.sharings.initial_sync"}}

Sharing¶

Sharing by links¶

Cozy to cozy sharing¶

Intents¶

Routes¶

POST /sharings/¶

Request¶

Response¶

GET /sharings/:sharing-id/discovery¶

Query-String¶

Example¶

POST /sharings/:sharing-id/discovery¶

Classical (x-www-form-urlencoded)¶

Example¶

JSON¶

Parameters¶

Example¶

POST /sharings/:sharing-id/preview-url¶

Request¶

Response¶

GET /sharings/:sharing-id¶

Request¶

Response¶

GET /sharings/news¶

Request¶

Response¶

GET /sharings/doctype/:doctype¶

Request¶

Response¶

PUT /sharings/:sharing-id¶

Request¶

Response¶

POST /sharings/:sharing-id/answer¶

Request¶

Response¶

POST /sharings/:sharing-id/public-key¶

Request¶

Response¶

POST /sharings/:sharing-id/recipients¶

Request¶

Response¶

POST /sharings/:sharing-id/recipients/delegated¶

Request¶

Response¶

POST /sharings/:sharing-id/members/:index/invitation¶

Request¶

Response¶

DELETE /sharings/:sharing-id/groups/:group-index/:member-index¶

Request¶

Response¶

PUT /sharings/:sharing-id/recipients¶

Request¶

Response¶

GET /sharings/:sharing-id/recipients/:index/avatar¶

Request¶

POST /sharings/:sharing-id/recipients/:index/readonly¶

Request¶

Response¶

POST /sharings/:sharing-id/recipients/self/readonly¶

Request¶

Response¶

DELETE /sharings/:sharing-id/recipients/:index/readonly¶

Request¶

Response¶

DELETE /sharings/:sharing-id/recipients/self/readonly¶

Request¶

Response¶

DELETE /sharings/:sharing-id/recipients¶

Request¶

Response¶

DELETE /sharings/:sharing-id/recipients/:index¶

Request¶

Response¶

DELETE /sharings/:sharing-id/groups/:index¶

Request¶

Response¶

DELETE /sharings/:sharing-id/recipients/self¶

Request¶

Response¶

DELETE /sharings/:sharing-id¶

Classical (`x-www-form-urlencoded`)¶