Managing flocks

#Managing flocks

This is the guide Priya follows when she starts Emu Watch's Coastal Volunteers: create the flock, invite Ben as a viewer and Ana as an editor, and keep the membership right as people come and go. By the end you'll have a flock with members at the right tiers, and know how to handle invitations, changes and departures.

Flocks are crews in the API, and your Nest is a project there: the endpoints below keep the API spelling.

#Prerequisites

• A signed-in account whose Nest role can create flocks. The built-in permissions: admin can manage flocks, editor can read and create them, viewer can only read. Priya needs no special standing — ordinary members with create permission can run a flock.
• The email addresses of the people you want to invite.

#Steps

#1. Create a flock

In the dashboard, open Flocks and click Create flock. Give it a name (required) and an optional description. You become the flock's first manager — Priya runs the Coastal Volunteers because she made it.

#HTTP

POST /api/v1/crews
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "name": "Coastal Volunteers",
  "description": "Emu Watch's coastal survey volunteers"
}

The response returns the new flock's id — you'll use it to share items with the flock. (A record reaches the flock through a share — see flock record access.)

#2. Invite members

From the flock's detail page, invite people by email and pick their tier. Ben, who just looks, is a viewer; Ana, trusted to correct species names, is an editor:

Tier	What it allows
viewer	See what is shared with the flock, however high the share's level goes
editor	That, plus change those records — up to what the share allows
manager	Everything above, plus delete on a manage share, and run the flock itself (invite, remove, retier)

A tier is a ceiling on each share, never a grant of its own. A manage share to the flock still gives an editor in it no delete.

POST /api/v1/crews/1f4a…/invitations
Authorization: Bearer sk-your-api-key
Content-Type: application/json

{
  "email": "ana@example.com",
  "tier": "editor"
}

Only flock managers can send invitations. An invitation expires after 7 days, and sending a new one to the same email replaces any pending invitation for that flock.

Remember what an invitation is not: joining the Coastal Volunteers gives Ben access to nothing by itself. He starts seeing things when somebody shares them with the flock — being in a flock grants nothing on its own.

#3. Accept the invitation

The invitee opens the invitation link (the /crews/accept page) while signed in, or posts the token directly:

POST /api/v1/crews/accept-invite
Authorization: Bearer <session-token>
Content-Type: application/json

{
  "token": "8c2e…"
}

The signed-in account's email must match the invited address — an invitation can't be redeemed by a different account. Accepting makes the membership active immediately; if the person was already a member, their tier is updated to the invited one.

#4. Manage members and invitations

From the flock detail page (or the API), flock managers can:

• Change a member's tier — PATCH /api/v1/crews/:id/members/:userId with { "tier": "viewer" }.
• Remove a member — DELETE /api/v1/crews/:id/members/:userId.
• Cancel a pending invitation — DELETE /api/v1/crews/:id/invitations/:inviteId.

Any member can remove themselves (leave the flock) — with one guard: the sole manager of a flock cannot leave. Promote someone else to manager first.

joined when security.crew_isolation is admin_manage (the default). Under strict, membership is absolute. See crew isolation modes.

#5. Choose which roles the flock can assign

A flock member has two independent settings, and the flock page shows them side by side:

• Tier — viewer, editor or manager. How far each share to this flock carries them. Every member has one — Ben's viewer tier, Ana's editor tier.
• Extra role — a Nest role such as species_editor, from this flock's catalogue. What they may DO. Optional; most members have none. This is how the Rangers hand their members the ranger role that can set a sighting's status.

The catalogue is what makes it safe to let anybody create a flock:

A flock manager chooses who gets a role. A Nest administrator chooses which roles exist to give.

If those were the same person, Priya could add an administrator role to the Coastal Volunteers' own menu and then take it. So:

1. A Nest administrator — Sam — turns on Flock-assignable for a role under Auth → Roles. Roles with administrator access cannot be marked — the toggle is disabled, and the API refuses it.
2. On the flock's page, under Roles this flock can assign, they press Edit and tick the roles this particular flock may use.
3. From then on the flock's own managers can pick from that list for each member, and cannot add to it.

PUT /api/v1/crews/{crewId}/roles
{ "roleIds": ["<role-id>", "<role-id>"] }

PATCH /api/v1/crews/{crewId}/members/{userId}
{ "roleId": "<role-id>" }        # the extra role; null clears it
{ "tier": "editor" }             # the tier in the flock

Either field may be sent alone. A roleId that is not on this flock's catalogue is refused.

#What you learned

• Flocks are created from the dashboard or POST /api/v1/crews; the creator is the first flock manager.
• Membership flows through email invitations with a tier attached; invitations expire after 7 days.
• Flock managers manage tiers, members, and invitations; the sole manager can't leave.
• A flock can hand out extra roles, but only from a catalogue a Nest administrator wrote.

#Next steps

• Sharing an item — hand the flock its first season of sightings
• Flock record access — what replaced flock scoping, and what an operator must run before upgrading
• Access control — roles, row scope and never-rules, from a collection's Access panel