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": "[email protected]"
  }
}

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	Authenticated but you’re not an admin
404	Membership or organization does not exist for you
422	Guard failed (last admin, owner demote, etc.)