Who can see what

#Start with Emu Watch

One small site explains the whole permission system, so it is worth two minutes before any mechanism gets a name.

Sam runs Emu Watch, a citizen-science sightings log. Volunteers walk the coast, and when they see a bird they log a sighting: where it was, when, a photo, and a few notes. Each sighting names a species, and the species collection holds those names in English, French and the local language. The photos themselves live in a file container called photos.

Priya signs up and logs a hundred sightings. They are hers, and nobody else can see them. She did not have to lock anything — logging them made them hers, and hers means private until she decides otherwise.

Her fellow volunteer Ben signs up too. He can log his own sightings. He cannot see Priya's. Being a member of the same site puts nothing of hers in front of him.

Priya is unsure about one identification, so she hands Ben that one sighting. Now Ben can see it — that sighting, and none of the others.

Priya starts the Coastal Volunteers and invites people. It is a flock: a named group she can hand things to. Ben joins as someone who just looks; Ana joins as someone trusted to fix things. Priya hands a season's sightings to the flock: Ana can correct the species and the notes, Ben can look, and anyone who joins next month gets the same — without Priya doing anything again.

Flocks are crews in the API: the dashboard says flock, the endpoints and the SDK say crew.

Some sightings belong on the public map. Sam has set one standing rule: any sighting marked verified appears on the public "This season" report, for members and visitors alike. Nobody publishes sightings to the map one by one; the rule does it.

Sam also runs a second flock, the Rangers. Their job needs one thing ordinary volunteers do not have: the power to mark a sighting verified, or unmark it.

And some places must never appear on a map at all — a sensitive nesting site, where publishing a point would bring people to it. Sam marks those sightings sensitive and they vanish for everyone: not the Coastal Volunteers, not the Rangers, not even Sam sees them until the mark is removed.

That story is the whole model. The rest of this page names its pieces.

Two more parts of Emu Watch appear elsewhere in the docs, and neither changes who can see what: a flow that emails a ranger when a sighting lands inside a reserve, and a monthly-summary blueprint. Both run under the same sentence as everybody else.

---

#The seven pieces

#1. Roles — what you may do

Sam decides what a volunteer is: someone who may log sightings, edit their own, and read what is verified. That decision is a role, and every person has one.

A role answers only one kind of question: which actions are allowed — read, create, edit, delete. It is a hard limit. If your role — or roles, where someone holds more than one — cannot edit sightings, nothing anywhere can make you able to edit a sighting: no share, no flock, no rule. Everything else on this page only ever decides which records, never what you can do to them.

Detail: Roles.

#2. What you see on your own

Why does Priya see her hundred sightings and Ben see none of them? Because for each role, each collection answers one question: without anyone sharing anything with you, which records do you see? Three possible answers: none, your own, or all of them.

Volunteers on Emu Watch see their own. That single setting is what makes Priya's sightings private by default — nothing had to be hidden, because nothing was ever open.

#3. Ownership

Every sighting has one owner. To begin with that is the person who logged it, so Priya never has to be given access to her own sightings — owning them is the access.

Ownership can move. When Priya leaves Emu Watch she hands her season to Ana: Ana now owns those sightings and reaches them as her own, and Priya keeps edit access unless somebody removes it. What does not move is who logged each sighting. That stays on the record forever, because it is history and history does not change — it is what the record's own page shows under "added by", and what an audit answers with.

Two facts, kept apart on purpose. One column holding both would mean either losing the history or stranding every sighting on an account nobody uses.

Detail: Ownership and handing over.

#4. Sharing — handing over one record

Priya handing Ben one sighting is a share. The owner of a record can hand it to:

• a person, by email;
• a flock, so everyone in it gets it;
• everyone, which is the ordinary "make this one public".

…choosing can view, can edit, or can manage (manage means they may share it onward). Sharing with everyone is view-only — "anybody on the internet may edit this" is not a thing worth making easy.

Two rules keep sharing safe:

• A share picks records, never abilities. If Ben's role cannot edit sightings, a "can edit" share still only lets him view. The share opened a door to the sighting; his role decides what he may do inside.
• A flock share is capped by your place in the flock. Priya hands a season to the Coastal Volunteers at "can edit". Ana, an editor in the flock, can edit those sightings. Ben, a viewer there, can only view them. Same share, two outcomes — everyone gets the lower of the share and their place in the flock.

And editing never includes sharing. Only the owner, or someone holding can manage on the item, can hand it on — otherwise anyone Priya let correct a species could quietly pass her sighting to strangers.

Sharing can be switched off per collection. Handing sightings around suits a volunteer survey; it does not suit a payroll table, where who sees a row should be a decision an administrator makes and not one each person makes for themselves. Each collection picks one of three answers to "who can share a record here": nobody, whoever owns it (the default), or curators only — meaning a role the administrator appointed, where owning the record is not enough.

Turning it off removes the shares that already exist. A switch that stopped new shares while leaving the old ones working would say one thing on the screen and do another in the data.

Detail: Sharing an item.

One sighting, or every sighting like it? Sharing with everyone publishes this record, because somebody decided so about it. Publishing a whole kind of record — "every sighting marked verified" — is a collection rule (piece 6), which applies to matching sightings on its own, including ones logged next year. Reach for a rule the moment you notice you are sharing the same thing twice.

#5. Flocks — groups of people

The Coastal Volunteers is a flock: just a group. Anyone can create one and invite people, and each member has a place in it — viewer, editor, or admin of that flock.

Being in a flock gives you nothing by itself. When Ben joined the Coastal Volunteers he gained access to nothing — until Priya shared the season with it. A flock is an address you can share things to, not a power you gain by joining.

One optional extra: Sam can allow a flock to hand its members specific extra roles — "species editor", say — but only from a menu Sam wrote. A flock can never invent powers for itself.

Detail: Flocks and Flocks and sharing.

#6. Collection rules — standing decisions that work by themselves

Set these under Settings → Access → Who else can see these records on the collection itself.

The public map is not five hundred shares. It is one rule Sam set on the sightings collection:

Everyone may view sightings where status is "verified".

A collection rule applies automatically, forever, to every record that matches. Nobody has to remember to do anything per sighting — a ranger marks it verified, and the rule does the rest. "Verified" is just an example; a rule can name any field and any value your data gives it.

#6b. Which fields someone may change

Sam wants volunteers to write notes and name a species — but not to set status, and not to move a sighting to a different place once it is logged.

Two lists on a role, beside the one that says which fields it can see:

• Columns they may change. Leave it empty and they may change any of them.
• Columns frozen after create. Set once, when the sighting is logged, and never again.

The distinction that matters: the list controlling what someone can see is a different list from what they can set. A ranger might read a private note a volunteer cannot, and a volunteer might set a note nobody else can edit.

#7. Never-rules

The sensitive nesting site is the one piece that subtracts instead of adding:

Sightings where "sensitive" is true may not be seen by anyone, no matter what.

No role, no share, no flock, no collection rule can get past a never-rule — by default not even Sam. It exists so that one mistake somewhere else cannot expose what must stay hidden.

Detail: Never-rules.

---

#The one sentence

Everything above combines into a single test, applied to every request:

You can do something to a record when your role allows the action, and the record is within reach — it is yours, or shared with you (directly or through a flock), or a collection rule covers it — and no never-rule forbids it.

Three things follow, and they answer most questions before they are asked:

• Ability comes only from roles. A share, a flock, a rule — none of them can add an action your role does not allow.
• Reach comes from ownership, shares and collection rules, and any one of them is enough. Priya reaches her sighting as its owner; Ben reaches it through a share; a visitor reaches it through the verified rule. Same sighting, three doors.
• Never-rules beat everything. The sighting at the nesting site has an owner, live shares and a verified status, and none of it matters.

---

#When something is not working

Walk the sentence in order. In practice the answer is almost always the first step.

1. "I shared it with Ben and he still cannot edit." His role has no edit permission. A share picks records, never abilities.
2. "Ana can edit the season but Ben cannot." Their places in the flock differ. A flock share gives each member the lower of the share and their place.
3. "A volunteer sees some sightings but not others." They see their own plus whatever reaches them — that is the reach working, not failing.
4. "Nobody can see it, even me." Check for a never-rule. It is the only piece that hides a record from its own owner — and each one carries a written reason so you can find out why.
5. "The Share tab says sharing is turned off." That collection is set to nobody. It is a per-collection setting on the Access screen, not something about you or the record.
6. "A sighting I logged stopped appearing in my own list." Somebody transferred it. You are still recorded as the person who added it — that never changes — but the owner is now somebody else. Ask them, or an administrator, to hand it back.

The Access inspector traces any decision gate by gate, which is faster than reasoning it out.

---

#Where to go next

Read these in order if you are setting a site up for the first time. Each one is whole on its own, so stop when you have what you need — and each one carries Emu Watch through, so the examples stay familiar.

If you want to…	Read
Work out whether you want a flock or a share	Flocks and sharing
Hand one sighting — one record — to somebody	Sharing an item
Hand a record over for good, or take one on	Ownership
Hide records from everyone, no matter what	Never-rules
Understand what a role really is, in detail	Roles
Copy a working setup	Recipes
Create a flock and invite people	Flocks
See exactly why someone can or cannot do something	Access control