web/docs/ORGANIZATIONS.md

Organizations and scoped access

One auth.User may belong to many organizations without creating another credential or browser session. Organizations own projects; projects own environments; environments own application services. Teams are optional groups of active organization members.

organizations.Service creates those resources and issues digest-backed, expiring, single-use invitations. An invitation may carry one direct role and up to sixteen reviewed team memberships. Acceptance verifies that the authenticated user's normalized email matches and applies the membership, role, teams, consumption marker, and audit event in one transaction. When OwnerRole is configured, creating or revoking an invitation carrying that role additionally requires a current active direct owner inside the same SQLite transaction. A broad access-management permission may administer ordinary invitations but cannot create or cancel owner access. Applications own invitation pages, email or out-of-band delivery, active-source checks before archival, and account recovery.

Creating an organization with an owner

For an existing authenticated user creating a business, use CreateOwnedOrganization with OwnerRole configured when constructing the service. Seed that role first. This commits the organization, active membership, direct organization-wide owner binding, and both creation/access audit events in one transaction. CreateOrganization.RequestID correlates those audit events. The owner must be an active user whose registration has completed.

The application authorizes creation and chooses the role; do not accept an owner role name from a browser or API payload. A customer-owner role can intentionally have different permissions from an installation's merchant-owner role. Creating a customer organization grants no authority in any other organization.

customers, err := organizations.New(store, organizations.Options{
	OwnerRole: "customer.owner", // Application-defined, already seeded.
})
if err != nil {
	return err
}
business, err := customers.CreateOwnedOrganization(ctx, organizations.CreateOrganization{
	Slug: "example-business", Name: "Example Business", OwnerUserID: principal.User.ID,
	RequestID: requestID,
})

Repositories implement OwnedOrganizationRepository to support this operation. There is no create-then-grant fallback: unsupported adapters return ErrOwnedCreationUnsupported. The older CreateOrganization and CreatePersonalOrganization retain their membership-only behavior; configuring OwnerRole does not silently change them. The separate account package still owns atomic public signup, including personal organization and credentials.

Membership and access lifecycle

Organizations and teams use optimistic revisions and reversible active/archived states. Archived objects keep their history but contribute no effective authority. Memberships may be suspended, reactivated, or removed; team membership can be removed independently. Configure OwnerRole when constructing the service before exposing membership-removal operations. The SQLite adapter then refuses to suspend or remove the final active direct owner.

Fresh-authentication administration pages should use ChangeMembershipStatus and RemoveMembershipIfCurrent, passing the exact displayed state as ExpectedStatus. The SQLite adapter acquires its write lock before checking that state, verifies the actor is still an active member of an active organization, and commits the lifecycle effects and audit together. Suspension removes team memberships; reactivation does not infer or restore them. Removal also revokes current direct bindings. A repository without the optimistic extension fails closed instead of falling back to a stale mutation.

For a reviewed access-administration page, use organizations.Members to list bounded active and suspended memberships, and access.OrganizationUserBindings to list only current direct, organization-wide user roles. The latter intentionally excludes team grants and project, environment, or service bindings. Replace a member's direct role with access.ReplaceOrganizationUserRole, passing the exact displayed binding IDs as ExpectedBindingIDs. The SQLite adapter serializes that replacement, rejects stale state, writes the new binding and audit event atomically, and will not demote the final active direct owner. The application must still authorize the administrator and bind any required fresh passkey assertion to the organization, target user, target role, and expected IDs.

access.Service evaluates a permission against a complete resource scope:

decision, err := accessService.Authorize(ctx, principal.User.ID, access.Scope{
	OrganizationID: organizationID,
	ProjectID:      projectID,
	EnvironmentID:  environmentID,
	ServiceID:      serviceID,
}, "telemetry.read")

A binding at organization scope covers its descendants. A narrower binding covers only its matching branch. The repository resolves team membership; a handler must never accept caller-supplied team identifiers as authority.

Platform roles in auth.Principal remain useful for installation health, account administration, and other explicitly global operations. They do not grant organization-data access. If an operator must inspect tenant data during an incident, use a reasoned break-glass grant. It expires within one hour and creates an append-only audit event in the same transaction.

An application that offers owner-assisted account recovery must not infer that authority from a broad administration page. Use the dedicated authrecovery.IssueAssistedRecovery boundary after an operation-bound passkey assertion. The SQLite adapter requires a current active direct owner binding and active target membership in the same transaction that invalidates the old credentials and records the organization-visible recovery audit. Team, break-glass, platform, and merely descriptive roles do not satisfy this owner check.

The SQLite adapter namespaces all tables, enforces active organization and team membership plus resource ancestry before accepting or evaluating a binding, and keeps invitations and sessions as digests. Applications remain responsible for database backup, filesystem ownership, retention, and presenting audit history to organization owners.