Rules on storage

Every bucket has a rule for each action on files. You set them in Studio, in the bucket’s settings (Create a bucket).

The five rules

Studio label	Field	Checked when
Who may read	`read_policy`	Downloading or showing a file
Who may upload new objects	`write_policy`	Uploading a new key
Who may list objects	`list_policy`	Listing; follows read if unset
Who may replace objects	`update_policy`	Overwriting an existing key; follows write
Who may delete objects	`delete_policy`	Deleting; follows write

A Public bucket lets anyone with a file’s address read it, while uploads, listing and deletes still follow their rules. Reading an object does not let someone enumerate the bucket: set listing to authenticated and public files are still only reachable by those who hold the URL. What your application’s requests may do. Studio administrators can always manage objects, whatever is set here.

What a rule sees: `$object`

Path	Meaning
`$object.key`	The whole key: `avatars/usr_abc/photo.jpg`
`$object.segments`	The key split on `/`
`$object.segments.0`	The first part
`$object.action`	`read`, `list`, `write`, `update`, `delete`

Plus $auth and the rest, as everywhere.

Design keys around rules

Put the owner first in the key, then one rule protects everything:

All of these rules pass:
- Check a value: $auth.user_id is set
- Compare values: $object.segments.0 equals $auth.user_id

Used as both write_policy and read_policy, this means each person reads and writes only under <their id>/…. For organizations, compare with $auth.org.

Recipes

Goal	Rules
Public avatars	Public bucket; `write_policy` = the owner-folder rule above
Private documents	`read_policy` and `write_policy` = owner-folder
Shared team files	Both = All of ( $auth.org is set;$ object.segments.0 equals $auth.org)
Server-written exports	`read_policy`: `authenticated`; `write_policy`: `service`
Staff-only uploads, public reads	Public bucket; `write_policy`: `role:staff`
Images only	Bucket Accepted types `image/*` (a bucket setting, not a rule)

Types and sizes are not rules

Accepted types (MIME patterns, checked against the file’s real contents) and Largest file are bucket settings, enforced regardless of who uploads. Use them together with rules. A signed link gives anyone who holds it one file for a short time, with no sign-in. A share link does the same for days and can be revoked. Both require the bucket to allow them, and creating one needs read access (signed) or a secret key (share). They bypass the caller’s identity by design, so treat them like passwords. See Download and links.

Refusals

Result	Meaning
`AuthenticationError`	The rule needs a signed-in user
`PermissionError`	The rule refused
`NotFoundError`	No such file, or the rule hides it
`PayloadTooLargeError`	Over the bucket’s size limit

The rule is evaluated before the file is looked up, so refusals never reveal whether a key exists.

Test it

await ada.storage.from("documents").upload(`${ada.userId}/x.txt`, "ok");      // allowed
await ada.storage.from("documents").upload(`${bob.userId}/x.txt`, "no");      // PermissionError
await visitor.storage.from("documents").download(`${ada.userId}/x.txt`);       // AuthenticationError

Storage

Storage access guide.

Values and paths

Segments and missing values.

Getting started

Build rules in Studio

The language

Where rules apply

Recipes

Test and debug

The five rules

What a rule sees: `$object`

Design keys around rules

Recipes

Types and sizes are not rules

Refusals

Test it

Storage

Values and paths

​The five rules

​What a rule sees: $object

​Design keys around rules

​Recipes

​Types and sizes are not rules

​Signed and share links

​Refusals

​Test it

Storage

Values and paths

The five rules

What a rule sees: `$object`

Design keys around rules

Recipes

Types and sizes are not rules

Signed and share links

Refusals

Test it