Team and tenant management

​

Motivation

• Administration → Teams is tenant-local and available to admin and super-admin. It creates a team for the acting administrator and renames teams they may administer.
• System administration → Tenant control is global and visible only with platform.admin (the protected system-admin role). It lists every registry tenant (including suspended/archived), expands one tenant’s users and access, updates lifecycle state, and provisions a tenant + initial project + new/existing user in one operation.

​

What a “team” is here

​

Design

​

Data model

​

System-admin tenant control

​

Registry and detail

• global Spatie roles and all effective permissions;
• active, inactive or soft-deleted account state;
• whether the user has all-project access under the current isolation mode;
• every membership in the selected tenant, with project key, membership role and scope allowlist.

​

One-step provisioning

1. a taken slug disables submission;
2. a new email reveals name + generated temporary password;
3. an existing active email switches automatically to associate existing, hides the password field and promises not to change the current password;
4. inactive and soft-deleted identities are blocked with an instruction to activate/restore them first.

​

Lifecycle

​

Decision rationale (ADR-style)

• Separate platform scope from tenant privilege. system-admin owns only platform.admin; super-admin owns the maximum tenant permission set, and both roles need membership before they may use tenant routes. A system administrator also holds companion super-admin so existing tenant route allowlists remain stable once a membership exists. ADR 0023 records the migration and rejected alternatives.
• Build over the vendor registry, not a new host table. The switcher already depends on tenants for names; a second host-owned name table would fork the source of truth. When the table is absent the feature degrades (below) rather than duplicating it. The tenants table is a registry, modelled like User — it is intentionally not tenant-aware and is excluded from TenantIdMandatoryTest (R30/R31), because its slug is the tenant id every other table references.
• Rename authorizes the target team by membership. The request’s active tenant does not prove access to another target. The service independently requires a membership in the target team, matching the rule AuthorizeTenantHeader enforces on every tenant route. A team you may not administer returns 404 (IDOR-safe: existence stays hidden). System administrators manage non-member tenants only through the global control plane.
• No MCP write tool — a deliberate R44 exception. Like the project registry, team management is an admin governance affordance, not an agent capability: a tenant_id is already usable as a stored legacy slug without a registry row, and a global write tool conflicts with the propose-only MCP posture. It ships HTTP + CLI only; the omission is documented in the controller and here rather than left implicit.
• default is reserved and non-operational. It may remain in legacy stored rows, but it never authorizes a dashboard or suppresses company onboarding. Renaming or re-creating it is rejected.

​

Worked example

1. GET /api/admin/teams returns only active teams represented by the identity’s memberships. default appears only when such a membership exists. System administrators also see only their operational memberships here; the global tenant roster lives under /api/system-admin/tenants.
2. Create → name Globex Corp. The slug auto-fills to globex-corp (editable, immutable after). POST /api/admin/teams writes the tenants row + an initial globex-corp project + a membership for the admin, atomically.
3. The page refetches /api/auth/me; the topbar switcher now lists Globex Corp, switchable immediately.
4. Rename Globex Corp → Globex Corporation: PATCH /api/admin/teams/globex-corp updates tenants.name; the switcher label updates without a reload.
5. A rename of a team the admin does not belong to → the API answers 404, and the row exposes no Rename action in the first place.

php artisan team:create --name="Globex Corp"        # attaches the first system-admin
php artisan team:rename globex-corp "Globex Corporation"
COMPANY_ADMIN_PASSWORD='temporary-secret' php artisan company:create --company="Contoso" --email="owner@contoso.test"

​

Gotchas

• The registry table is optional — the feature degrades, it never 500s. When Schema::hasTable('tenants') is false (the AI-Act package was never migrated), create/rename raise TeamRegistryUnavailableException, which the controller maps to a clean 503 with error: team_registry_unavailable (R14/R43). The list still renders with humanised slug names.
• The slug is immutable. It is the tenant_id every document, chunk, membership and chat log joins to — renaming changes only the display name. To “rename the id”, create a new team and migrate content.
• Every identity sees only membership teams on tenant surfaces. This includes system administrators. Create therefore attaches the acting user as a member; global non-member administration belongs exclusively to the system control plane.
• Inactive users cannot authenticate. Both session login and bearer-token issuance require users.is_active=true; disabling an account is now an effective access-control action rather than a display-only flag.
• Soft-deleted emails remain reserved. Restore the account instead of creating a second identity. This matches the database uniqueness contract and prevents hidden duplicate owners.