So in Manticore's upcoming Chwala storage adapter,

Here is what Chwala can expect from Manticore:

1. GET /api/documents/ returns an array of documents that have been loaded in Manticore and have been created/edited by the requesting user.
2. GET /api/documents/:uuid returns a document with the given Chwala ID.
3. POST /api/documents/ lets you upload a file with multipart/form-data, and a field uuid which is the Chwala ID of the document you're handing over to Manticore.
4. PUT /api/documents/:uuid lets you overwrite a document with a new one, while keeping the UUID (for example when someone replaces the file in the roundcube web interface). The request does not take any fields, only a file. This ends any corresponding session (because the base file is now different).
5. DELETE /api/documents/:uuid deletes the document from Manticore and ends it's corresponding session.

A document is expected to look like:

{
  "title": "Project Report",
  "uuid": "<chwala file uuid>"
  "created": "2015-10-16T14:30:43.651Z",
  "date": "<last edit time>",
  "creator": {
    "name": "Administrator"
    "email": "admin@admin.com",
  },
  "editors": [{
    "name": "Administrator"
    "email": "admin@admin.com",
  }],
  "access": [{
    "email": "admin@admin.com",
    "type": "write"
  }, {
    "email": "test@user.com",
    "type": "read"
  }, {
    "email": "another@user.com",
    "type": "deny"
  }],
  "live": true
}

title indicates the metadata title of the file, and not necessarily the filename.
editors represents the people who have made edits in a document (so not passive observers).
live of course indicates whether this document's session currently has any members in it (so people who have an editor window open with this doc).
access is an array that lets you map a user's email to read, write, and deny. If an email is not present in this array, it is treated as deny. This can be modified by a PATCH request to /api/documents/:uuid, I shall describe the semantics of that here once I have something that works ready.

Note that some of these methods don't work in the same way I've advertised just yet, but I'm making them so.

And here is what Manticore expects from Chwala's API:

PUT /document/:uuid takes a file and overwrites the corresponding file with it in Chwala's storage.

PS:
I was previously thinking of a user_token for security purposes, but it looks like no one needs to implement that alternative form of authentication because I've just spent some time investigating cross-iframe communication with the postMessage API - that should let Chwala provide it's Manticore auth token to roundcube, which can then provide this token to the iframe - no credentials within the iframe src required.

An update: Chwala may or may not store user login credentials for external storage based one what the administrator chooses. However, it becomes impractical to present a login dialog to Manticore users when they want to save a document.

So here's what we can go with for now: Let's say the first person to click on a document in Roundcube and be taken to Manticore is Alice. Then, Alice (the 'owner') will first be shown a login dialog to enter her credentials to the external storage, in Roundcube - so that Chwala can retrieve the file and POST it to Manticore.

Chwala can cache a mapping of the file UUID with the encrypted username/password combination of Alice.

When someone saves the file via Manticore, it is sent to Chwala, which uses the cached credentials to write it to the external service.

Therefore, Manticore doesn't need to show a new save-login dialog and everything is kept simple.

Update: @machniak informed me that it shall be simpler for Chwala to just 'register' the uuid to Manticore. Then, Manticore can send a request to retrieve that file when needed.

This means that we now expect an additional GET /document/:uuid method available on Chwala.
And, the POST method on Manticore will now only take uuid and not a file.

A couple of updates:

For simplicity's sake, I've changed some requests and the new API is as follows:

1. GET /api/documents/ returns an array of documents that have been loaded in Manticore and have been created/edited by the requesting user.
2. GET /api/documents/:id returns a document with the given ID.
3. POST /api/documents/ is a request containing three fields: id, title which can be the filename, and access which is an array of access control entries as shown in the example document. Manticore will fetch the actual file from Chwala using the provided id. Normally you should initialize the access array with an entry containing the creator of the session even if no one else is collaborating.
4. PUT /api/documents/:id lets you overwrite a document with a new one, while keeping the UUID. This request can have an empty body, Manticore will take care of fetching the file like above.
5. GET /api/documents/:id/access returns the access control array for a document.
6. PUT /api/documents/:id/access lets you update the access policy by a new complete access control array. So no incremental updates for now!
7. DELETE /api/documents/:uuid deletes the document from Manticore and ends it's corresponding session.

Additionally, an access array is now of the form:

"access": [{
  "identity": "admin@admin.com",
  "permission": "write"
}, {
  "identity": "test@user.com",
  "permission": "read"
}, {
  "identity": "another@user.com",
  "permission": "deny"
}],