Teams
On this page
Introduction#
Team management is a feature-gated module. All team routes and logic are only registered when the teams feature is enabled:
// config/magic-starter.php
'features' => [
Features::teams(),
],
All team endpoints require auth:sanctum middleware. Routes are handled by TeamController, TeamMemberController, TeamInvitationController, and TeamPhotoController.
Team CRUD#
List Teams#
GET /teams
Returns a paginated list of all teams the authenticated user owns or belongs to, ordered by name.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
per_page |
integer | 15 | Items per page (max 100) |
Response: 200 OK
{
"data": [
{
"id": "9a8b7c6d-...",
"name": "Acme Corp",
"personal_team": false,
"owner_id": "1a2b3c4d-...",
"user_role": "owner",
"profile_photo_url": "https://...",
"created_at": "2026-01-15T10:30:00.000000Z",
"updated_at": "2026-01-15T10:30:00.000000Z"
}
],
"links": { "..." : "..." },
"meta": { "..." : "..." }
}
Controller: TeamController@index
Create Team#
POST /teams
Creates a new team. The authenticated user becomes the owner.
Request Body:
| Field | Type | Rules |
|---|---|---|
name |
string | required, string, max:255 |
Response: 201 Created
{
"data": {
"id": "9a8b7c6d-...",
"name": "New Team",
"personal_team": false,
"owner_id": "1a2b3c4d-...",
"user_role": "owner",
"profile_photo_url": null,
"created_at": "2026-03-25T12:00:00.000000Z",
"updated_at": "2026-03-25T12:00:00.000000Z"
}
}
Contract: CreatesTeams (overridable via service container binding)
Controller: TeamController@store
Show Team#
GET /teams/{team}
Returns a single team. Requires view policy authorization (user must belong to the team).
Response: 200 OK
{
"data": {
"id": "9a8b7c6d-...",
"name": "Acme Corp",
"personal_team": false,
"owner_id": "1a2b3c4d-...",
"user_role": "admin",
"profile_photo_url": "https://...",
"created_at": "2026-01-15T10:30:00.000000Z",
"updated_at": "2026-01-15T10:30:00.000000Z"
}
}
Controller: TeamController@show
Update Team#
PUT /teams/{team}
Updates team details. Requires update policy authorization (owner only).
Request Body:
| Field | Type | Rules |
|---|---|---|
name |
string | required, string, max:255 |
photo |
file | nullable, image, max:1024 KB |
Response: 200 OK -- returns updated TeamResource.
Contract: UpdatesTeams (overridable via service container binding)
Controller: TeamController@update
Delete Team#
DELETE /teams/{team}
Deletes the team. Requires delete policy authorization (owner only). Personal teams cannot be deleted -- returns a 422 validation error.
If the deleted team was the user's current active team, the user is automatically switched to their next available team.
Response: 200 OK
{
"data": null,
"message": "Team deleted successfully."
}
Error (personal team): 422 Unprocessable Entity
{
"message": "You may not delete your personal team.",
"errors": {
"team": ["You may not delete your personal team."]
}
}
Contract: DeletesTeams (overridable via service container binding)
Controller: TeamController@destroy
With the restorable delete on, this endpoint trashes the team instead and answers with the end of its restore window:
{
"data": {
"restore_until": "2026-11-28T12:00:00.000000Z"
},
"message": "Team deleted. Its owner can restore it until the restore window closes."
}
The same refusals apply, including the subscription guard, and the contract is TrashesTeams.
Restore Team#
POST /teams/{team}/restore
Registered only with the restorable delete on. Brings a trashed team back. Requires restore policy authorization (owner only). This is the one endpoint that finds a trashed team; every other team endpoint answers 404 for it.
Restoring a team that is already live changes nothing and answers 200, so a client that sends the request twice is not punished.
Response: 200 OK -- returns the TeamResource with a message.
Error (window closed): 422 Unprocessable Entity
{
"message": "This team can no longer be restored.",
"errors": {
"team": ["This team can no longer be restored."]
}
}
Contract: TrashesTeams (overridable via service container binding)
Controller: TeamController@restore
Restorable Delete#
By default DELETE /teams/{team} deletes the team for good. The restorable-teams feature makes that delete reversible: the team is hidden for a window, its owner can restore it, and a scheduled command deletes it once the window has closed. It is off until you switch it on, and while it is off nothing about team deletion changes.
Switching it on takes three things in the consuming application:
- The column.
magic-starter:installpublishesadd_soft_deletes_to_teams_tablewith the teams feature; on an existing install copy it fromvendor/fluttersdk/magic-starter-laravel/database/migrations/intodatabase/migrations/. It addsdeleted_atand an indexed, nullablerestore_until. - The trait. The team model uses
Illuminate\Database\Eloquent\SoftDeletes. The publishedApp\Models\Teamstub does; add it by hand to an older one. The package's ownModels\Teamdoes not, so that applications that never opt in keep a teams table without the column. - The feature and the schedule.
// config/magic-starter.php
'features' => [
\FlutterSdk\MagicStarter\Features::teams(),
\FlutterSdk\MagicStarter\Features::restorableTeams(),
],
'teams' => [
'restore_days' => 30, // MAGIC_STARTER_TEAM_RESTORE_DAYS
],
// routes/console.php
use Illuminate\Support\Facades\Schedule;
Schedule::command('magic-starter:purge-trashed-teams')->daily();
The package registers the command and does not schedule it. Without the schedule line a trashed team is never deleted.
What a trash does#
TrashesTeams::trash() runs in one transaction:
- clears
current_team_idfor every user whose active team is this one, with a query-builder update that ignores$fillable. A soft delete is an update and never triggers the foreign key'snullOnDelete, so without this the pointer would name a team nobody can see; - cancels the pending invitations, because a link to a hidden team must not be acceptable;
- writes
restore_until,teams.restore_daysdays from now (0closes the window at once); - soft deletes the team.
Members stay attached, so a restore brings the team back with the people it had. The team disappears from GET /teams and from every relation, because the model's soft delete scope hides it. A restore does not put the pointers back (they are each person's choice, and they have been somewhere else since) and does not bring the invitations back; the owner invites again.
The subscription guard of the plain delete applies to a trash as well (Actions\SubscriptionGuardedTrashTeam), so a team a store or Stripe is still billing is refused with the same sentence.
What a restore does#
TrashesTeams::restore() clears deleted_at and restore_until in one write, and refuses with a 422 once restore_until is not in the future. A trashed team with no restore_until (trashed by other means) has no window to close and is restored.
The purge#
php artisan magic-starter:purge-trashed-teams
Selects the trashed teams whose restore_until is not in the future and deletes each through DeletesTeams, so the subscription guard and the photo cleanup run as they do for any team. DeletesTeams is the purge: on a model that soft deletes it force deletes. Each team is read again under a lock first, so a restore that lands after the walk loaded it wins.
| Outcome | Meaning |
|---|---|
| Deleted | Removed with its photo, memberships and invitations. |
| Held | The billing guard refused. Logged as well as printed, left trashed, and tried again on the next run. |
| Restored | Its owner restored it after the walk loaded it. Skipped. |
| Failed | Reported, and the run moves on. The exit code is non-zero. |
Purge finished: 12 deleted, 1 held, 0 restored, 0 failed.
A team model that does not use SoftDeletes, or a table without restore_until, has nothing to purge and the command says so.
Account deletion#
An account purge deletes the teams the user trashed too, for good and through DeletesTeams: OwnedTeams::includingTrashed() reads them, and a trashed team a subscription still bills holds the purge back like any other. A trashed team does not count as a shared team, so it never blocks scheduling the deletion.
Team Members#
List Members#
GET /teams/{team}/members
Returns all members of the team, including the owner. The owner is injected with the owner role. Requires view policy authorization.
Response: 200 OK
{
"data": [
{
"id": "1a2b3c4d-...",
"name": "John Doe",
"email": "[email protected]",
"profile_photo_url": "https://...",
"role": "owner"
},
{
"id": "5e6f7g8h-...",
"name": "Jane Smith",
"email": "[email protected]",
"profile_photo_url": "https://...",
"role": "admin"
}
]
}
Controller: TeamMemberController@index
Update Member Role#
PUT /teams/{team}/members/{user}
Updates a team member's role. Requires manageMembers policy authorization (owner or admin). Cannot change the role of the team owner (returns 403).
Request Body:
| Field | Type | Rules |
|---|---|---|
role |
string | required, string, in:admin,editor,member |
Response: 200 OK
{
"message": "Team member updated successfully."
}
Error (changing owner role): 403 Forbidden
Cannot change role of team owner.
Controller: TeamMemberController@update
Remove Member#
DELETE /teams/{team}/members/{user}
Removes a member from the team. Requires manageMembers policy authorization (owner or admin). Cannot remove the team owner (returns 403).
If the removed member's current_team_id points at this team, it is cleared, so their next read lands on their personal team instead of the team they were removed from. A member whose current team is another team keeps it.
Response: 200 OK
{
"message": "Team member removed successfully."
}
Error (removing owner): 403 Forbidden
Cannot remove team owner.
Contract: RemovesTeamMembers (overridable via service container binding)
Controller: TeamMemberController@destroy
Leave Team#
DELETE /teams/{team}/leave
Allows the authenticated user to leave a team. The team owner cannot leave (returns 403). If the user is not a member, returns 404.
If the team being left was the user's current active team, current_team_id is cleared and the user falls back to their personal team (getCurrentTeamOrPersonal()). A user whose current team is another team keeps it.
Response: 200 OK
{
"message": "You have left the team."
}
Error (owner leaving): 403 Forbidden
Team owner cannot leave the team. Delete the team instead.
On the owner's personal team, which cannot be deleted either:
You may not leave your personal team.
Error (not a member): 404 Not Found
You are not a member of this team.
Contract: RemovesTeamMembers
Controller: TeamMemberController@leave
Team Invitations#
List Invitations#
GET /teams/{team}/invitations
Returns a paginated list of pending invitations for the team, ordered by most recent. Requires manageInvitations policy authorization (owner or admin).
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
per_page |
integer | 15 | Items per page (max 100) |
Response: 200 OK
{
"data": [
{
"id": "a1b2c3d4-...",
"team_id": "9a8b7c6d-...",
"email": "[email protected]",
"role": "member",
"token": "abc123def456...",
"created_at": "2026-03-25T12:00:00.000000Z",
"updated_at": "2026-03-25T12:00:00.000000Z"
}
],
"links": { "..." : "..." },
"meta": { "..." : "..." }
}
Controller: TeamInvitationController@index
Create Invitation#
POST /teams/{team}/invitations
Sends a team invitation to an email address. Requires manageInvitations policy authorization. Returns 422 if an invitation already exists for that email or the user is already a team member.
Request Body:
| Field | Type | Rules |
|---|---|---|
email |
string | required, email, max:255 |
role |
string | required, string, in:admin,editor,member |
Response: 201 Created
{
"data": {
"id": "a1b2c3d4-...",
"team_id": "9a8b7c6d-...",
"email": "[email protected]",
"role": "member",
"token": "abc123def456...",
"created_at": "2026-03-25T12:00:00.000000Z",
"updated_at": "2026-03-25T12:00:00.000000Z"
}
}
Error (duplicate invitation): 422 Unprocessable Entity
{
"message": "An invitation has already been sent to this email.",
"errors": {
"email": ["An invitation has already been sent to this email."]
}
}
Error (already a member): 422 Unprocessable Entity
{
"message": "This user is already a member of the team.",
"errors": {
"email": ["This user is already a member of the team."]
}
}
Contract: InvitesTeamMembers (overridable via service container binding)
Controller: TeamInvitationController@store
Cancel Invitation#
DELETE /teams/{team}/invitations/{invitation}
Cancels (deletes) a pending invitation. Requires manageInvitations policy authorization. The invitation must belong to the specified team (returns 404 otherwise).
Response: 200 OK
{
"data": null,
"message": "Invitation canceled successfully."
}
Controller: TeamInvitationController@destroy
Accept Invitation#
POST /invitations/{token}/accept
Accepts a team invitation using a token. The authenticated user's email must match the invitation email (case-insensitive). Expired invitations return 410 Gone and are automatically deleted.
If the user is already a member, the invitation is deleted and a success message is returned.
Response: 200 OK
{
"data": null,
"message": "Invitation accepted. You have joined the team."
}
Error (email mismatch): 403 Forbidden
{
"message": "This invitation was sent to a different email address."
}
Error (expired): 410 Gone
{
"message": "This invitation has expired."
}
Confirming a different email (opt-in): Sign in with Apple can hand the app a private relay address
(@privaterelay.appleid.com), so someone invited at their real address can never match. Set
invitation_confirm_email_mismatch (MAGIC_STARTER_INVITATION_CONFIRM_EMAIL_MISMATCH, off by default) and a user
who may confirm is asked first instead of refused. They may confirm when they hold a Sign in with Apple link that has
not been revoked, or their address is on privaterelay.appleid.com (the whole domain, case-insensitive). Everyone
else keeps the 403 above, whatever the request carries.
409 Conflict, with nothing attached and the invitation left in place:
{
"message": "This invitation was sent to a different email address. Confirm to join with this account.",
"code": "email_mismatch",
"requires_confirmation": true,
"masked_email": "a***@example.com"
}
masked_email is the invited address reduced to its first character and its domain, for the client to show. Repeat
the request with {"confirm_email_mismatch": true} to join; only a true value confirms. The repeat goes through
AcceptsTeamInvitations like any other accept, so the expiry, already-a-member and ensureCanJoin() checks all still
run, and the token is used up by the join. The invitation token is the proof that the person was invited: anyone
holding the link and an Apple account can use this, which is why it is off by default.
Controller: TeamInvitationController@accept
Team Photos#
Team photo endpoints are only available when both teams and profile-photos features are enabled.
Upload Team Photo#
POST /teams/{team}/profile-photo
Uploads or replaces the team's profile photo. Requires update policy authorization (owner only). The previous photo is deleted from disk before storing the new one.
Request Body: multipart/form-data
| Field | Type | Rules |
|---|---|---|
photo |
file | required, image, max:2048 KB |
Response: 200 OK -- returns updated TeamResource.
The photo is stored using the disk configured in magic-starter.team_photo_disk (falls back to magic-starter.profile_photo_disk, then filesystems.default). The storage path is configured via magic-starter.team_photo_path (default: team-photos).
Controller: TeamPhotoController@update
Delete Team Photo#
DELETE /teams/{team}/profile-photo
Removes the team's profile photo. Requires update policy authorization (owner only). The photo file is deleted from disk and profile_photo_path is set to null. profile_photo_url answers null again, and the client draws its own placeholder.
Response: 200 OK -- returns updated TeamResource.
Controller: TeamPhotoController@delete
Switch Current Team#
PUT /user/current-team
Switches the authenticated user's active team. The request is authorized via the switchTo policy gate (user must belong to the team).
Request Body:
| Field | Type | Rules |
|---|---|---|
team_id |
string | required, uuid, exists in teams table |
Response: 200 OK
{
"data": { "...UserResource..." },
"message": "Team switched successfully"
}
Error (not a member): 403 Forbidden
{
"message": "You are not a member of this team."
}
Request: SwitchTeamRequest (authorization is handled in the request's authorize() method via Gate::allows('switchTo', $team))
Controller: AuthController@switchTeam
Lifecycle Events#
A host that tells people when something happens to their team (a member joined, the household was deleted, ownership passed) listens to six events instead of overriding the actions:
| Event | Dispatched | Properties |
|---|---|---|
Events\TeamMemberJoined |
After a member is attached: an invitation accepted (AcceptTeamInvitation) or a user added by email (AddTeamMember). |
teamId, userId, actorId (the joiner when they accepted, the user who added them otherwise) |
Events\TeamMemberRemoved |
After a member is detached by RemoveTeamMember, which serves both the remove and the leave endpoints. |
teamId, userId, actorId (equal to userId when the member left) |
Events\TeamDeleted |
After a team is deleted for good by DeleteTeam: the delete endpoint with the restorable delete off, magic-starter:purge-trashed-teams, the admin panel, and the account purge for each team the user owned. |
teamId, ownerId, memberIds (everyone who belonged, the owner included, in no particular order) |
Events\TeamTrashed |
After TrashTeam hides a team for its restore window. |
teamId |
Events\TeamRestored |
After TrashTeam brings a trashed team back inside the window. |
teamId |
Events\TeamOwnershipTransferred |
After TransferTeamOwnership hands a team to another member: a host's own transfer, the admin panel, and the account purge when it hands on a departing owner's team. |
teamId, previousOwnerId, newOwnerId, actorId |
use FlutterSdk\MagicStarter\Events\TeamDeleted;
use FlutterSdk\MagicStarter\Events\TeamMemberJoined;
use Illuminate\Support\Facades\Event;
Event::listen(TeamMemberJoined::class, fn (TeamMemberJoined $event) => /* tell the owner */);
Event::listen(TeamDeleted::class, fn (TeamDeleted $event) => /* tell every former member */);
Four rules hold for all six:
- After the commit. Each event implements
ShouldDispatchAfterCommit. The account purge calls these actions inside its own transaction, so a listener hears of a change only once the whole of it has committed, and never hears of one that rolled back. Outside a transaction an event is dispatched at once. - Once, and only for a change. An action that refuses fires nothing: a join the plan or
ensureCanJoin()refuses, the owner being removed, a delete or trash the billing guard refuses, a restore after the window closed, a transfer to a user who is not a member. Neither does a call that changes nothing: removing someone who is not a member, restoring a team that is not trashed, transferring a team to the owner it already has. - Keys, not models. The payload is keys as strings, whatever the key type, and nothing else: no model, name or address, so a queued listener loads what it needs when it runs.
TeamDeletedcannot load its members, because the team and its memberships are gone by then, so it carriesmemberIds, read before the members are detached. - A bound action owns its event. The events are dispatched by the default actions. An application that binds its own class over
AddsTeamMembers,RemovesTeamMembers,DeletesTeams,TrashesTeams,TransfersTeamOwnershiporAcceptsTeamInvitationswithout extending the default has to dispatch them itself. Extending the default and overriding one hook keeps them.
Two departures follow from what the actions do. Deleting a team detaches its members without firing TeamMemberRemoved for each: TeamDeleted and its memberIds are the record. Deleting an account detaches the user from the other teams they belonged to the same way, and fires no event for it.
Transferring Ownership#
TransferTeamOwnership makes the new owner the owner and leaves the outgoing owner on the team as an admin. A host whose teams have fewer roles overrides outgoingRole() and keeps the rest of the transfer, the event included:
use FlutterSdk\MagicStarter\Actions\TransferTeamOwnership;
use FlutterSdk\MagicStarter\Contracts\TransfersTeamOwnership;
use FlutterSdk\MagicStarter\Enums\Role;
class TransferHouseholdOwnership extends TransferTeamOwnership
{
protected function outgoingRole(): Role
{
return Role::MEMBER;
}
}
// AppServiceProvider::register()
$this->app->bind(TransfersTeamOwnership::class, TransferHouseholdOwnership::class);
Return anything but Role::OWNER: the new owner takes that role in the same transfer.
Authorization#
TeamPolicy#
TeamPolicy is automatically registered by the service provider when the teams feature is enabled. Consumers can override it:
// In your AuthServiceProvider
Gate::policy(Team::class, CustomTeamPolicy::class);
App providers boot after package providers, so the override takes precedence.
Policy Abilities Summary#
| Ability | Allowed For | Used By |
|---|---|---|
view |
Team members (owner + members) | TeamController@show, TeamMemberController@index |
update |
Owner only | TeamController@update, TeamPhotoController |
delete |
Owner only | TeamController@destroy |
restore |
Owner only | TeamController@restore |
manageMembers |
Owner or admin role | TeamMemberController@update, TeamMemberController@destroy |
manageInvitations |
Owner or admin role | TeamInvitationController@index, store, destroy |
switchTo |
Team members (owner + members) | SwitchTeamRequest authorization |
Models#
Team#
Class: FlutterSdk\MagicStarter\Models\Team
| Property | Type | Description |
|---|---|---|
id |
string | Primary key (UUID or integer via ConditionallyUsesUuids) |
user_id |
string | Owner's user ID (foreign key) |
name |
string | Team name |
personal_team |
bool | Whether this is a personal (non-deletable) team |
profile_photo_path |
string|null | Stored photo path on disk |
profile_photo_url |
string|null (read) | Stored photo URL, or null when none is stored |
created_at |
Carbon|null | Timestamp |
updated_at |
Carbon|null | Timestamp |
deleted_at |
Carbon|null | Set on a trashed team; only with the restorable delete |
restore_until |
Carbon|null | End of a trashed team's restore window; only with the restorable delete |
Relationships:
| Method | Type | Description |
|---|---|---|
owner() |
BelongsTo | The user who owns the team |
users() |
BelongsToMany | Members via team_user pivot (with role, uses MagicStarter::membershipModel()) |
invitations() |
HasMany | Pending TeamInvitation records |
Fillable: user_id, name, personal_team, profile_photo_path
Casts: personal_team as boolean, restore_until as datetime
Appends: profile_photo_url
TeamUser (Pivot)#
Class: FlutterSdk\MagicStarter\Models\TeamUser
Extends Illuminate\Database\Eloquent\Relations\Pivot. Uses the team_user table.
| Property | Type | Description |
|---|---|---|
id |
string | Primary key |
team_id |
string | Foreign key to teams |
user_id |
string | Foreign key to users |
role |
string|null | Member role (admin, editor, member) |
created_at |
Carbon|null | Timestamp |
updated_at |
Carbon|null | Timestamp |
Uses ConditionallyUsesUuids for runtime UUID/integer PK switching.
TeamInvitation#
Class: FlutterSdk\MagicStarter\Models\TeamInvitation
| Property | Type | Description |
|---|---|---|
id |
string | Primary key |
team_id |
string | Foreign key to teams |
email |
string | Invited email address |
role |
string | Role to assign upon acceptance |
token |
string | Unique acceptance token |
expires_at |
Carbon|null | Expiration timestamp (null = no expiry) |
created_at |
Carbon|null | Timestamp |
Fillable: email, role, token, expires_at
Casts: expires_at as datetime
Relationships:
| Method | Type | Description |
|---|---|---|
team() |
BelongsTo | The team this invitation is for |
Methods:
| Method | Returns | Description |
|---|---|---|
isExpired() |
bool | true if expires_at is set and in the past |
scopeValid() |
Builder | Scope to non-expired invitations (null or future date) |
Roles#
Roles are defined in FlutterSdk\MagicStarter\Enums\Role:
| Role | Value | Assignable | Description |
|---|---|---|---|
OWNER |
owner |
No | Determined by team.user_id, not pivot |
ADMIN |
admin |
Yes | Can manage members and invitations |
EDITOR |
editor |
Yes | Standard elevated role |
MEMBER |
member |
Yes | Default member role |
The owner role is never assigned via the pivot table -- it is resolved at runtime by comparing team.user_id with the user's ID. Only admin, editor, and member are valid values for invitation and member role updates.
HasTeams Trait#
Trait: FlutterSdk\MagicStarter\Traits\HasTeams
Applied to the User model to provide team relationship methods.
| Method | Returns | Description |
|---|---|---|
ownedTeams() |
HasMany | Teams where the user is the owner (user_id) |
teams() |
BelongsToMany | Teams the user is a member of (via team_user pivot with role) |
personalTeam() |
Model|null | The user's personal team (personal_team = true) |
currentTeam() |
BelongsTo | The user's currently active team (current_team_id) |
allTeams() |
Collection | Merged owned + member teams, sorted by name |
getCurrentTeamOrPersonal() |
Model|null | Current team with personal team fallback |
belongsToTeam(Model $team) |
bool | Whether the user owns or is a member of the team |
ownsTeam(Model $team) |
bool | Whether the user owns the team (user_id match) |
hasTeamRole(Model $team, string $role) |
bool | Whether the user has the given role on the team (does not check ownership) |