Memberships

The link between a user and an organization. Org-scoped. Used to manage who’s on the team and what role they hold.

Operations

Operation	Method + path	Token scope	Role	Notes
List members	GET /organizations/:organization_id/members.json	read or write	Organization member	Paginated, admins first
Change member role	PATCH /organizations/:organization_id/members/:id.json	write	Organization admin	Owner and last-admin guards apply
Remove member or leave organization	DELETE /organizations/:organization_id/members/:id.json	write	Organization admin or the current member	Owner and last-member guards apply

Resource shape

{
  "id": "dHaBjN",
  "role": "admin",
  "is_owner": true,
  "created_at": "2026-04-01T10:00:00Z",
  "updated_at": "2026-04-01T10:00:00Z",
  "user": {
    "id": "nFsKwR",
    "name": "Yaro",
    "email": "yaro@example.com"
  }
}

role is member or admin. is_owner is true for the organization owner — the owner cannot be removed or demoted.

List

GET /organizations/:organization_id/members.json

Returns members of the organization, ordered admins-first. Paginated.

Update

PATCH /organizations/:organization_id/members/:id.json

{ "membership": { "role": "admin" } }

Requires admin role on the organization. Cannot demote the only remaining admin. Cannot demote the organization owner.

Delete (remove member or leave)

DELETE /organizations/:organization_id/members/:id.json

Removes the membership. If you remove yourself, you’ve left the organization.

Cannot remove:

• The organization owner
• Yourself if you are the sole member
• The only remaining admin

Returns 204 No Content on success, 422 with errors on a guarded failure.

Errors

Code	When
401	Missing token, or read token attempting a write
403	Not an admin, or the action is never permitted (removing or demoting the owner)
404	Membership or organization does not exist for you
422	Guard failed (last admin, sole member, etc.)