Ownership and handing over
Who owns a record, how ownership moves when somebody leaves, and why who created it never changes.
#Two facts about every record
Priya logs a sighting on Emu Watch. From that moment the sighting carries two facts about her, and it is worth separating them before anything else:
| The fact | What it is | Does it change? |
|---|---|---|
| Priya added this | History. It was true then and it is true forever. | Never |
| Priya owns this | Access. It decides what she can do with it today. | It can move |
Most of the time they are the same person and nobody has to think about it. Owning your own sightings is what makes them yours, and nobody has to grant you access to your own work.
They come apart the day somebody leaves.
Flocks are crews in the API, and your Nest — the site you sign in to — is a
project there.
#The day Priya leaves
Priya is moving on. She has four hundred sightings on Emu Watch, and Ana is taking over her stretch of coast.
Without a way to hand records over there are only two things anybody can do, and both are bad:
- Edit the sightings to say Ana added them. Now the site's history is wrong. Every "added by" line lies, and any question that starts "who logged this?" gets the wrong answer forever.
- Leave everything as it is. The sightings stay attached to an account nobody uses. They sit in a scope that reaches nobody, and the only way to touch them is for an administrator to bypass the rules — every time, forever.
So ownership moves and history does not. Ana becomes the owner: the sightings appear in her own list, she can edit and share them like anything else of hers, and she can hand them on again. The sightings still say added by Priya, because Priya added them.
#What happens to the old owner
By default they keep edit access — as an ordinary share, listed on the record's Share tab like any other, and removable by the new owner whenever they like.
That is deliberate. Handing over a record you have been working on for a year should not lock you out of it mid-sentence, and the new owner can always take the share away once the handover is done.
If you want a clean break — a genuine confiscation rather than a handover — ask for one explicitly, and no share is left behind. It is the option you have to say out loud, rather than the one you get by not thinking about it.
If the collection has sharing turned off, no share is left behind and the handover tells you so. A collection where sharing is switched off is one where an administrator decided access is not handed around, and a transfer must not quietly be the exception.
#Who is allowed to hand a record over
Two kinds of people:
- The owner. Giving away something that is yours is part of owning it, the same way sharing it is.
- Anyone whose role grants
transferon that collection. This is the administrator's route, and it is what makes an orderly handover possible when somebody has already left and cannot do it themselves.
manage on the collection includes it, as manage includes everything.
Nothing else does — and in particular, edit does not. Being allowed to
change a record does not make you allowed to reassign it. edit is the
permission handed out most freely, and if handing a record over rode inside it,
every editor in the Nest could quietly reassign anybody's records.
#What handing over does not do
- It does not widen anybody's access. The new owner still needs a role that can read the collection. Handing a sighting to somebody whose role cannot see sightings gives them a sighting they cannot see — unhelpful, but not a leak.
- It does not change who added the record. Said three times on this page because it is the whole point.
- It does not move anything else. Existing shares stay exactly as they are. A sighting shared with the Coastal Volunteers is still shared with the Coastal Volunteers.
#What "your own records" means afterwards
A collection set to Only their own shows you the records you own — which is now a slightly bigger idea than "the ones you added":
- a sighting you logged and nobody has moved → yours;
- a sighting somebody handed to you → yours, whoever added it;
- a sighting you logged and handed away → not yours any more.
That last one is the one people ask about. Handing a record over genuinely hands it over: it leaves your list, and if the new owner did not leave you a share, you no longer reach it. Anything else would make "transfer" mean "co-own", quietly, and the person who gave a record away would keep every owner's right over it — including the right to give it away again.
#The API
POST /api/v1/collections/sightings/records/{id}/transfer
{ "userEmail": "ana@example.com" }
POST /api/v1/collections/sightings/records/{id}/transfer
{ "userId": "…", "keepAccess": false }
Name exactly one of userId or userEmail. keepAccess defaults to
true — the previous owner is left an edit share; pass false for a clean
break.
The new owner must be a person in this Nest. Transferring to somebody who already owns it succeeds and changes nothing, so a retry is safe.
#Next
- Sharing an item — lending a record rather than handing it over
- Permissions — how ownership fits with roles, flocks and rules
- Roles — where the
transferpermission is granted