Environment 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:

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

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

# Set a user's permission
keyenv permissions set [email protected] write --env production

# Remove a user's permission
keyenv permissions delete [email protected] --env production

# View your own permissions
keyenv permissions my

Via the SDK

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

# 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.

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

# 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