Sharing an item

Hand one record or file to specific people or to a flock — the levels, who may share, expiry, and revoking.

#Sharing an item

Priya logged a sighting. Ben wants to see it. That is the whole of this page.

Sharing works the same way for a record in a collection and for a file in storage. If you own it, you can share it — unless the collection says otherwise, which is the next section.

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

#Is sharing available here?

Sharing is discretionary access: the person holding a record decides who else reaches it, and an administrator finds out afterwards by opening the record. That is right for a sightings log. It is not right for everything, so each collection chooses one of three answers on its Access screen:

Setting What it means
Nobody No sharing here. Records are reached through roles and flocks only.
Whoever owns the record The default, and what every collection did before this setting existed.
Curators only Owning a record is not enough — the sharer needs a role with manage on the collection.

If the Share tab tells you sharing is turned off, that is this setting and not something about you.

Turning it off removes the shares that already exist. People and flocks who were given access to individual records lose it, and turning sharing back on later does not bring them back. The screen asks before it does this. The alternative — blocking new shares while quietly honouring old ones — would mean the setting said one thing and the data did another.

#Three ways to say who

#By name

Pick people and choose what each may do. This is the everyday case: Priya opens the sighting, shares it with Ben by his email, done. Nothing has to exist first — no flock, no setup. Ben is in no flocks at all, and it does not matter.

Use it when you can name the people, and when the list is not going to change much.

#With a flock

Hand it to a whole flock. When Priya shares a season's sightings with the Coastal Volunteers, everyone in the flock reaches them — and the list stays right by itself as people join and leave.

Use it when the audience is a group rather than a list — "the Coastal Volunteers", "the Rangers" — or when you would otherwise be re-sharing the same thing every time somebody new arrives.

#With everyone

Make this one sighting public. No name, no flock, no list — anybody who can reach the site at all sees this record, including people who are not signed in wherever the collection allows that.

It is view only. There is no version of this that lets strangers edit.

Use it for the occasional sighting you want out in the open. Do not use it as a way to publish a whole category: if you find yourself making every verified sighting public one at a time, what you want is a collection rule — "anyone may view sightings where status is verified" — which covers the verified sightings you have and the ones nobody has logged yet, and costs nothing per sighting. There is a limit on how many records in one collection can be published individually, and it exists to catch exactly this mistake before it becomes a list somebody maintains by hand.

You do not have to choose once and for all. The same sighting can be shared with two people by name, with three flocks, and with everyone, all at the same time, each at its own level. They add up: you get the most generous one that applies to you.

#The three levels

Each level includes the ones before it.

Level See it Change it Share it onward
View ✓
Edit ✓ ✓
Manage ✓ ✓ ✓

Deleting needs Edit for a share by name. For a flock share it needs Edit and flock admin — deleting somebody else's record is the one action where being senior in the flock is required as well as being trusted with the item.

#Why Edit does not include sharing

If it did, anybody you let edit something could hand it on to people you have never heard of, and nothing would tell you. Ana can correct the species on Priya's sightings; she cannot pass Priya's records to another flock. That is why Manage is a separate level from the start.

As the owner you always have Manage on your own items, whether or not anybody granted it to you.

#The one rule to remember

A share decides WHICH items somebody reaches. Their role decides WHAT they may do. You always get the more restrictive of the two.

Worked through:

Ben is a volunteer on Emu Watch. Volunteers may read sightings; they may not edit other people's. Priya shares a sighting with Ben at Edit. Ben can view it. He cannot edit it.

The share was not ignored — it is what let Ben see the sighting at all. It just cannot invent an edit permission that Ben's role does not have.

And for flocks, the second narrowing:

Priya shares a season's sightings with the Coastal Volunteers at Edit. Ana is an editor in the flock: she can correct the species names. Ben is a viewer in the flock: he can only view them.

One share, two outcomes. A flock share is narrowed twice — by the level granted and by your place in that flock, and you get the lower of the two. A share by name has no flock place, so only the level applies. Your role caps both.

One more thing outranks every share: a never-rule. A sighting at a sensitive nesting site stays invisible to Ben and the whole flock, live shares and all.

#Editing is not moving

A share lets you edit a record in place. It never lets you move it — the columns that say where a record lives, its flock and its creator, cannot be changed through a share. Ana can correct a species on Priya's sighting; she cannot re-home the sighting into her own flock. This is built in, not something you configure.

#Expiry

A share can carry an expiry date. After it passes, the access simply stops; the row stays until somebody revokes it, and nothing continues to reach the item through it.

Expired shares are excluded everywhere they are counted, including the access inspector — so the numbers there mean live access, not history.

#Taking it back

Revoke a share and the access ends immediately for everybody it covered.

You may revoke a share if you own the item, or if you hold Manage on it — the same test as creating one.

There is one deliberate exception. If the item has since been deleted, anyone who could have revoked the share before can still revoke it now. Otherwise a leftover share would be unremovable through the API, and leftovers matter: item ids can recur (a re-created collection, an import that preserves ids), and a stale share that matches a recycled id is access nobody granted.

The system also sweeps automatically — deleting a record takes its shares with it, and tearing down a collection takes all of that collection's shares.

#Who is it shared with?

Ask for any item you can read:

GET /api/v1/shares?itemType=record&collection=sightings&itemId=<id>

You get every live share on it, naming the flock or the person, with its level and expiry.

If you cannot read the item, you get not found — not "forbidden". A forbidden would confirm the item exists, and since this endpoint takes an arbitrary id, that would turn it into a way to probe for them.

#Sharing an item you do not own

You can, if somebody gave you Manage on it. What you cannot do is hand on more than you have:

  • You cannot share an item you cannot read.
  • You cannot grant a level above the one you hold.
  • You cannot grant somebody an action their role does not allow — nobody can.

#The API

POST /api/v1/shares
{ "itemType": "record", "collection": "sightings", "itemId": "…",
  "userId": "…", "level": "view", "expiresAt": null }

POST /api/v1/shares
{ "itemType": "file", "itemId": "…", "crewId": "…", "level": "edit" }

POST /api/v1/shares
{ "itemType": "record", "collection": "sightings", "itemId": "…",
  "everyone": true, "level": "view" }

Name exactly one of userId, userEmail, crewId or everyone. Sending two is refused rather than resolved in favour of one — a request carrying two does not know which access it is granting, and quietly honouring either would create access nobody reviewed.

everyone must be the literal true, and its level must be view. Both are checked rather than corrected: a caller asking to let the internet edit a record has misunderstood something, and silently storing view instead would leave them believing the opposite of what happened.

Re-sharing the same item with the same person or flock changes the existing share rather than adding a second one, so there is never a pair of rows to reconcile.

DELETE /api/v1/shares/:id

#Next