# Teams

Create teams, manage members, and control access to your projects.

Source: https://keyenv.dev/docs/web-app/teams/

Teams are the organizational unit in KeyEnv. Every project belongs to a team, and team membership determines who can access your secrets. When you sign up, a personal team is created automatically.

## Team Lifecycle

### Creating a Team

1. Click your team name in the sidebar
2. Click **Create Team**
3. Enter a team name (up to 100 characters)
4. Click **Create**

The creator automatically becomes the team's first **admin**. New teams start on the Free plan.

### Viewing Team Details

Navigate to **Team** in the sidebar to see:

- Team name and plan
- All current members with their roles
- Pending invitations

### Renaming a Team

Team admins can rename a team from the team settings page. Click the edit icon next to the team name, enter the new name, and save.

### Deleting a Team

Team deletion is handled by system administrators. If you need to delete a team, contact support. Deleting a team permanently removes all projects, secrets, and member associations.

> **Warning**
>
> Team deletion cannot be undone. Make sure to export any secrets you need before requesting deletion.

## Team Roles

KeyEnv has two team-level roles: **admin** and **member**.

| Capability | Admin | Member |
|---|---|---|
| View team members and invitations | Yes | Yes |
| Access all environments (bypasses env permissions) | Yes | No |
| Invite and remove members | Yes | No |
| Change member roles | Yes | No |
| Create and delete projects | Yes | No |
| Manage billing and plan | Yes | No |
| Set default permissions | Yes | No |
| View audit logs | Yes | No |
| View and edit secrets | Yes | Per-environment |
| Manage environment permissions | Yes | Only if granted `admin` on that environment |

> **Note**
>
> Team admins automatically have full access to all environments in every project. Regular members get access based on their per-environment permissions. See [Environment Permissions](/docs/web-app/permissions) for details.

### Changing a Member's Role

1. Go to **Team** in the sidebar
2. Find the member in the list
3. Click the role dropdown next to their name
4. Select the new role

You cannot demote the last admin. Every team must have at least one admin at all times.

## Inviting Members

Only team admins can invite new members.

### Sending an Invitation

1. Go to **Team** in the sidebar
2. Click **Invite Member**
3. Enter the invitee's email address
4. Select a role (`admin` or `member`)
5. Click **Send Invite**

The invitee receives an email with a link to join. If they do not have a KeyEnv account, they will be prompted to create one.

> **Note**
>
> Members receive email notifications when invited to a team, when their role changes, and when they are removed from a team.

### Invitation Expiration

Invitations expire after **30 days**. If an invitation expires:

- The invitee can no longer accept it
- An admin must resend the invitation to generate a fresh link

Resending refreshes both the token and the expiration date.

### Invitations and Member Limits

Pending invitations count toward your team's member limit. On the Free plan (1 member limit), you cannot send an invitation because the creator already fills the slot. Upgrade to Pro for unlimited members.

### Managing Pending Invitations

Admins can view, resend, and revoke pending invitations:

- **View**: Go to the **Invitations** tab on the team page
- **Resend**: Click the resend button next to the invitation
- **Revoke**: Click the revoke button to cancel a pending invitation

## Removing Members

Team admins can remove any member from the team:

1. Go to **Team** in the sidebar
2. Find the member in the list
3. Click the remove button
4. Confirm the removal

Non-admin members can only remove themselves (leave the team). They cannot remove other members.

> **Warning**
>
> Removed members immediately lose access to all project secrets. Their environment-level permissions are cleaned up automatically.

You cannot remove the last admin from a team. The sole admin must promote another member to admin before leaving.

## Team Roles and Environment Permissions

KeyEnv uses a two-tier permission model:

1. **Team role** (`admin` or `member`) -- controls team-level operations
2. **Environment permission** (`none`, `read`, `write`, or `admin`) -- controls per-environment secret access

How they interact:

- **Team admins** bypass environment permissions entirely. They have full `admin` access to every environment in every project.
- **Team members** rely on their per-environment permissions. If a member has no permission set for an environment, they have `none` (no access).

### Default Permissions

Only team admins can configure default permissions for each environment. When a new member joins the team, they automatically receive these defaults. For example, you might set:

- `development` -> `write` (all new members can edit dev secrets)
- `staging` -> `read` (all new members can view staging)
- `production` -> `none` (no production access by default)

See [Environment Permissions](/docs/web-app/permissions) for full details on managing per-environment access.

## Plan Limits

Team capabilities depend on your plan:

| Resource | Free | Pro | Enterprise |
|---|---|---|---|
| Team members | 1 | Unlimited | Unlimited |
| Projects | 3 | Unlimited | Unlimited |
| Secrets per environment | 100 | Unlimited | Unlimited |
| Environments per project | 3 | Unlimited | Unlimited |

When you reach a limit, you can still use existing resources but cannot create new ones. Upgrade to Pro to remove all limits.

See [Billing](/docs/web-app/billing) for details on upgrading and managing your plan.

## Audit Trail

All team actions are logged:

- Team created
- Member invited, accepted, removed
- Role changes
- Invitation sent, resent, or revoked

Access the audit log from the team settings page. Only team admins can view audit logs.

## Best Practices

1. **Keep multiple admins** -- If your sole admin loses access, no one can manage the team. Always have at least two admins for critical teams.
2. **Review access regularly** -- Remove members who no longer need access. Check pending invitations and revoke stale ones.
3. **Use service tokens for CI/CD** -- Do not share personal credentials with automated systems. Create scoped [service tokens](/docs/web-app/service-tokens) instead.
4. **Set default permissions thoughtfully** -- Configure project defaults so new members get appropriate access without manual setup.
5. **Restrict production access** -- Give most members `read` or `none` for production and reserve `write`/`admin` for senior engineers and DevOps.