Members and invitations

How a person is added to a team by email, phone or username, what happens when they have no account yet, and how roles are changed from the list.

A team grows from /team/members. This guide covers the members list, the form that adds someone, the two ways the kit handles a person with no account yet, and the notifications each step sends. Which identities the form accepts is decided by the base: see Configure sign-in and registration.

The members list

/team/members shows two tables:

Members, with their name, their identity and their role in this team. From each row a member with update members changes the role, and one with delete members removes the person from the team.
Pending invitations, with the email and the date, for people who were invited and have not registered. A member with delete members cancels one. This table is hidden when invitation_mode is auto_provision, because in that mode nothing stays pending.

Removing a member detaches them from the team and sends them a notification, in the account and by email. Their account is untouched, and so is their membership in any other team.

Adding a member

Create member opens /team/members/create. It asks first how the person is identified, with one button per identity your product accepts in config/auth.php → login_identities, plus Auto-detect, which reads whatever is typed: an address is an email, a number is a phone, anything else is a username. Then it asks for the identity, a role from the team's roles, and, when the person does not exist yet, a name.

What happens on save depends on whether an account already has that identity.

The account exists

The person is added to the team at once, with the role picked in the form. They are told in their account and by email, and the team appears in their switcher on their next visit. Someone who is already a member is refused with a message.

The account does not exist

config/teams.php → invitation_mode decides:

'invitation_mode' => env('TEAM_INVITATION_MODE', 'approval_required'),

Mode What the kit does

approval_required Writes a TeamInvitation with the email and the role, and emails the address a link to the registration page with the email filled in. The person joins the team the moment they register, with that role, and the invitation is deleted. Until then it shows in the pending table. Only an email can be invited this way: a phone or a username with no account is refused with Phone invitations are not available yet.

auto_provision Creates the account on the spot with the name typed in the form and the identity given, adds it to the team with the role, and, when the identity is an email, sends a link to set a password. A phone gets an account but no email, so the person signs in through the phone code. Nothing is left pending.

Mode	What the kit does
`approval_required`	Writes a `TeamInvitation` with the email and the role, and emails the address a link to the registration page with the email filled in. The person joins the team the moment they register, with that role, and the invitation is deleted. Until then it shows in the pending table. Only an email can be invited this way: a phone or a username with no account is refused with Phone invitations are not available yet.
`auto_provision`	Creates the account on the spot with the name typed in the form and the identity given, adds it to the team with the role, and, when the identity is an email, sends a link to set a password. A phone gets an account but no email, so the person signs in through the phone code. Nothing is left pending.

A registration is matched against every pending invitation for its email, so a person invited by three teams joins the three when they register.

The plan's limit

Members and pending invitations both count against the users limit of the team's plan. When the team has reached it, the Create member button stays on the members list but disabled, and a message under the title names the limit and asks to upgrade the plan; a team without a plan is at its limit from the start. Opening the list shows no warning: the form refuses with the same message only when an invitation is saved, so a saved link to it does not get past the limit. A member without create members does not see the button at all. See Team plans and billing for where the limit is set.

Changing a member's role

The edit control on a member's row opens a dialog with the team's roles. Saving removes the previous role and assigns the chosen one; a person holds exactly one role per team. The owner's own row has no edit control: the owner keeps the owner role for as long as the team exists.

Permissions involved

Action	Permission, on the `team` guard
See the members and invitations	`retrieve members`
Add a member or invite one	`create members`
Change a role	`update members`
Remove a member or cancel an invitation	`delete members`

The owner passes all four without holding them. The default role a new member receives, user as shipped, holds only retrieve members. See Team roles and permissions to change that.

What is sent

Event	Class	Channel
Added to the team	`App\Notifications\Members\AddedToTeamNotification`	Account and email
Removed from the team	`App\Notifications\Members\RemovedToTeamNotification`	Account and email
Invited, `approval_required`	`App\Mail\Member\InvitedToTeamEmail`	Email
Account created, `auto_provision`	`App\Mail\Member\ProvisionedToTeamEmail`	Email

The two notifications go through the base's notification system, so each person's own preferences decide whether the email is sent. See Send notifications on the base's site.