Organizations and sharing

Your app's users each act in one of your app's organizations: a customer's company, a team, a household. Storage keeps every organization's files apart, the same way your tables keep their rows apart, and lets you, the app's owner, share your own files with the organizations you choose.

Two kinds of item live in a storage, and they follow different rules:

Every organization has its own space

Your storages are shared containers: every organization can use every storage, and each one sees only its own folders and files inside it. Two organizations can each have an invoices folder at the root of the same storage, and neither learns of the other's.

• A listing shows the caller's own organization's items, and your items shared with it. Nothing else is listed, searched, counted or downloadable.
• Another organization's file, folder or storage is the same 404 as one that does not exist, on every route. A uid from elsewhere confirms nothing.
• A new folder or file belongs to the organization of the folder it is created in, or to the caller's organization at the root of a storage.

You see every organization's items in the console, each labeled with its organization.

Sharing your own folders and files

Your own items are private to you until you share them. Sharing is set on a folder or a file, in the console's Storage section: open the storage, open the item's menu, and choose Sharing….

A setting on a folder covers everything inside it that has no setting of its own, all the way down. A file or subfolder can override its folder in either direction: a private file in a folder shared with everyone, or one file shared from an otherwise private folder. The root of a storage is Only me.

A change takes effect at once, for the item and everything that inherits from it, narrowing included: un-share a folder and its files stop appearing in every organization's next listing.

In the console each of your items carries a small badge: a lock (only you), people (all organizations), a building with a count (only these), or a globe (the storage is public). A faded badge means the setting is inherited; hover it to see from which folder.

Shared means seen, not managed

An organization you share an item with can:

• see it in listings, marked "sharedByOwner": true in the API's response,
• read its details, get a link to it and download it,
• upload its own files into a folder you shared with it.

It cannot rename, move, change or delete your item, or create folders inside your shared folder. Each of those is a 403 with STORAGE_SHARED_READ_ONLY.

A file an organization uploads into your shared folder belongs to that organization and is private to it, whatever the folder's setting says. Otherwise any member could share a file with every other organization just by dropping it in a shared folder.

Public storages

Sharing decides who sees an item in a listing. In a public storage, anyone who has a file's link can open it, signed in or not, whatever its sharing says. For that reason the console marks your items in a public storage with a globe and describes their sharing as who they are "listed for". Keep anything you share selectively in a private storage.

Two meanings of "owner"

Storage uses the word in two places, and they are unrelated:

• The app's owner is you, the builder. Sharing is about your items.
• A file's owner (owner_uid) is the app user a file belongs to, set when it is uploaded. The isOwner policy condition reads that, to limit users to their own files (how).

The two combine: with isOwner on storage:read, a user opens only files they own, so your shared items, which no app user owns, are listed for them but cannot be opened. Leave isOwner off storage:read if your users should open what you share.

Errors

Next