platform-admin

Remove Principal

Remove a principal from the app (ISS-26 for humans; extended 2026-08-05 to agents). Frederick, 2026-08-05: "I want to be able to remove users from the app. Right now I can only deactivate." — and, the same day, tried to remove two agent principals ("QA Temp Agent", genuine dead cruft, and "Rooster Pipeline", the identity the whole build/CS pipeline authenticates as) and got refused on both, because the only guard was kind != 'human'. See registry.AgentInUse for the full incident.

A HUMAN's removal is unchanged: soft (registry.remove_human — the row stays for attribution, but the person cannot sign in, holds no access, and disappears from principal lists), and their open work moves automatically to an active same-role successor (registry.find_same_role_successor, computed BEFORE removal deletes the role memberships it is read from) or falls back to a manual COO card.

An AGENT's removal (registry.remove_agent) is the same soft-removal shape, but refuses with a 422 explaining why if the agent still holds live act-capability — never bare, since a bare 403/422 here would look exactly like the old blanket refusal it replaces. Agents never own open work directly (their bound human does), so there is no successor or reassignment card for this branch.

post/api/platform/principals/{principal_id}/remove

Request

  • Base URL: https://api.pigeonly.com (the document declares no server; this is the origin it was published from)
  • URL: https://api.pigeonly.com/api/platform/principals/{principal_id}/remove
  • Auth: none declared

Path parameters

principal_idstring uuid required

Response

Successful Response

object required

Changes

No recorded changes to this operation across all 1 revision of this API.