# Environment Permissions

Control access to secrets with granular environment-level permissions.

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

Environment permissions give you fine-grained control over who can access secrets in each environment. This allows teams to restrict production access while giving developers full access to development environments.

## Permission Roles

Each team member can have one of four permission levels per environment:

| Role | View Secrets | Modify Secrets | Manage Permissions |
|------|--------------|----------------|-------------------|
| `none` | ❌ | ❌ | ❌ |
| `read` | ✅ | ❌ | ❌ |
| `write` | ✅ | ✅ | ❌ |
| `admin` | ✅ | ✅ | ✅ |

> **Note**
>
> Team admins automatically have full access to all environments regardless of individual permission settings.

## Managing Permissions

### Via the Web App

1. Navigate to your project's secrets page
2. Click the **⋮** menu next to the environment tabs
3. Select **Manage Access**
4. In the modal:
   - View current permissions for all team members
   - Add new permissions by selecting a team member and role
   - Edit existing permissions by clicking on the role badge
   - Remove permissions with the delete button

### Via the CLI

```bash
# List permissions for an environment
keyenv permissions list --env production

# Set a user's permission
keyenv permissions set user@example.com write --env production

# Remove a user's permission
keyenv permissions delete user@example.com --env production

# View your own permissions
keyenv permissions my
```

### Via the SDK

```typescript
// Node.js
const permissions = await client.listPermissions('project-id', 'production');
await client.setPermission('project-id', 'production', 'user-id', 'write');
```

```python
# Python
permissions = client.list_permissions("project-id", "production")
client.set_permission("project-id", "production", "user-id", "write")
```

## Default Permissions

Configure default permissions that are automatically applied when new team members join.

### Setting Defaults

1. Go to **Project Settings**
2. Find the **Default Permissions** section
3. Set the default role for each environment
4. Click **Save Changes**

When a new member joins the team, they'll automatically receive these default permissions.

> **Warning**
>
> Default permissions only apply to new team members. Existing members keep their current permissions.

## Service Token Permissions

Service tokens can be scoped to specific environments for additional security:

- **Single-environment tokens**: Create tokens that can only access one environment
- **Read-only tokens**: Use `read` scope for CI/CD that only needs to pull secrets
- **Write tokens**: Use `write` scope only when the token needs to modify secrets

```bash
# Example: CI/CD token with read-only access to production
KEYENV_TOKEN="env_..." keyenv pull --env production
```

## Team Roles and Environment Permissions

KeyEnv uses a two-tier permission model. Understanding how these layers interact is key to setting up secure access for your team.

### Team Admin vs Environment Permission

**Team role** (`admin` or `member`) is set at the team level and applies across all projects. **Environment permission** (`none`, `read`, `write`, `admin`) is set per-environment within a project.

These two layers interact as follows:

- **Team admins** automatically receive `admin` access to every environment in every project. No environment-level permission is checked. This means team admins can always view secrets, modify secrets, and manage permissions in any environment.
- **Team members** have no implicit access. Their effective permission for a given environment is determined solely by their environment-level permission. If no permission is set, they have `none` (no access).

### Permission Resolution

When a user tries to access secrets in an environment, the system resolves their effective permission:

1. Check if the user is a team admin. If yes, grant `admin` access (done).
2. Look up the user's environment-level permission for this specific environment.
3. If no explicit permission exists, the effective role is `none`.

This means a team member with `write` on `development` and `read` on `production` can edit dev secrets but only view production secrets. A team admin skips this check entirely.

### Default Permissions and New Members

When a new member joins the team (by accepting an invitation), default permissions are applied automatically:

1. The system checks each project for configured default permissions.
2. For each environment with a default role, the new member receives that role.
3. If no default is configured for an environment, the member gets `none`.

Only team admins can configure project default permissions. Defaults do not retroactively change existing members' permissions.

### Permission Cleanup on Member Removal

When a member is removed from a team:

- All their environment-level permissions across all projects are removed
- Access is revoked immediately
- Service tokens created by that user continue to work (revoke them separately if needed)

### Practical Examples

**Small startup (5 developers, 1 DevOps lead)**

Set up the DevOps lead as a team admin. Add all developers as team members with defaults:

```
development: write   (everyone can edit dev secrets)
staging:     write   (everyone can deploy to staging)
production:  read    (developers can view but not change production)
```

The DevOps lead, as a team admin, automatically has full access to production for deployments and rotations.

**Agency with client projects**

Use team members for contractors with minimal access:

```
development: write   (contractors work in dev)
staging:     none    (no staging access)
production:  none    (no production access)
```

Keep at least two internal staff as team admins for full access.

**Large team with environment owners**

Promote environment leads to `admin` on their specific environments:

```
development: Most developers → write, Dev Lead → admin
staging:     QA team → write, QA Lead → admin
production:  DevOps → admin, Everyone else → read
```

Environment admins can manage permissions for their environment without needing to be team admins.

## Best Practices

### Principle of Least Privilege

- Give users the minimum access they need
- Use `read` for users who only need to view secrets
- Reserve `admin` for team leads who manage access

### Production Security

- Limit `write` and `admin` access to production
- Use `read` access for most developers in production
- Require approval workflows for production changes

### Audit Trail

All permission changes are logged in the audit trail:

- Who changed the permission
- What the previous and new roles were
- When the change occurred

## Common Scenarios

### Development Team Setup

```
development: All developers → write
staging:     All developers → write
production:  All developers → read, DevOps → admin
```

### Contractor Access

```
development: Contractor → write
staging:     Contractor → read
production:  Contractor → none
```

### CI/CD Pipeline

```
Service Token: read access to required environments only
```