Membership lifecycle

Every change to who belongs to an organization goes through the Memberships, Invitations and Organizations contracts. Each verb enforces the organization's invariants inside one transaction, records an audit entry and emits a webhook event — so a host never writes a role or a status onto a model by hand.

The single-owner rule

An organization always has an owner, and ownership is transferred, never assigned.

• MembershipRole::assignable() lists the tiers a console or API may hand out — Owner is not among them. Validate one incoming tier with $role->isAssignable() and route a request for Owner to transferOwnership() instead.
• The last owner cannot be demoted, removed or leave: those raise LastOwner. The count of owners is taken with the owner rows locked, so two owners stepping down at the same moment cannot both succeed.
• owners($organizationId) lists the active owners. Organizations created before ownership was transfer-only may hold more than one; treat that as data to reconcile, not a pattern to extend.

The verbs

Leaving

use Cbox\Id\Organization\Contracts\Memberships;
use Cbox\Id\Organization\Exceptions\LastOwner;

try {
    app(Memberships::class)->leave($organizationId, $userId);
} catch (LastOwner $e) {
    // "You are the only owner of organization [...], so you cannot leave it.
    //  Transfer ownership to another member first, or archive the organization."
    return back()->withErrors(['leave' => $e->getMessage()]);
}

Transferring ownership

use Cbox\Id\Organization\Contracts\Memberships;
use Cbox\Id\Organization\Exceptions\OwnershipTransferRefused;

try {
    $newOwner = app(Memberships::class)->transferOwnership($organizationId, $currentOwnerId, $memberId);
} catch (OwnershipTransferRefused $e) {
    // $e->reason is an OwnershipTransferRefusal: not_owner, target_not_member,
    // target_not_active or same_member — a stable code for an API error body.
}

Both membership rows are read with a row lock, in one statement ordered by id, so the transfer is atomic against a concurrent remove, leave, role change or second transfer, and two transfers crossing between the same people cannot deadlock. The organization is never without an owner at any point in the transaction.

An owner archiving their organization

archiveAsOwner($organizationId, $userId) has exactly archive()'s semantics — the Deleted status, the cache invalidation, idempotence — plus a check that $userId holds an active owner membership, taken under a row lock so an ownership transfer cannot slip in between the check and the archive. The audit entry is attributed to that user.

Isolation

Every guard above binds the organization in its WHERE clause as well as relying on the tenant scope. Under TenantContext::withoutScope() — a provisioning job, a backfill — a guard that relied on the scope alone would see every organization's rows: a delete would remove the person everywhere, the owner count would include other organizations' owners, and a transfer could promote a member of a different organization.

Events

The legacy names stay because outbound provisioning and usage metering key off them, and existing webhook endpoints may subscribe to them by name. New integrations subscribe to the first column. Payloads: Webhook events.

The member's tier also travels in tokens as the org_role claim.