# Core Concepts

Understand the key concepts behind KeyEnv.

Source: https://keyenv.dev/docs/getting-started/concepts/

Understanding these concepts will help you get the most out of KeyEnv.

## Projects

A **project** is a collection of secrets for a single application or service. Each project can have multiple environments.

- Projects are identified by a unique ID
- You can switch between projects with `keyenv switch`
- Projects can be shared with team members

## Environments

**Environments** are isolated sets of secrets within a project. Common environments include:

| Environment | Purpose |
|-------------|---------|
| `development` | Local development |
| `staging` | Pre-production testing |
| `production` | Live application |

Each environment has its own set of secrets with the same keys but different values:

```
# development
DATABASE_URL=postgres://localhost/mydb

# production
DATABASE_URL=postgres://prod-server/mydb
```

## Secrets

A **secret** is a key-value pair. Secrets have:

- **Key**: The environment variable name (e.g., `DATABASE_URL`)
- **Value**: The sensitive data
- **Version**: Incremented on each update
- **Description**: Optional documentation

## Version History

Every change to a secret is tracked. You can:

- View the history of changes with `keyenv history SECRET_NAME`
- See who made each change and when
- Audit access and modifications

## Environment Permissions

**Environment permissions** control who can access secrets in each environment. Permission levels:

| Role | Description |
|------|-------------|
| `none` | No access |
| `read` | View secrets only |
| `write` | View and modify secrets |
| `admin` | Full access + manage permissions |

This allows you to:
- Give developers full access to `development`
- Restrict `production` to senior engineers
- Grant read-only access for debugging

> **Note**
>
> Team admins automatically have full access to all environments.

## Service Tokens

**Service tokens** are API keys for CI/CD and automated systems. They:

- Have limited permissions (specific project/environment)
- Can be scoped to a single environment for extra security
- Never expire but can be revoked
- Are used instead of user authentication in automated pipelines

```bash
# In CI/CD, set the token as an environment variable
export KEYENV_TOKEN="env_..."
keyenv pull
```

## Team Collaboration

KeyEnv supports team workflows:

- **Members** can view and modify secrets
- **Admins** can manage team settings and members
- All changes are attributed to the user who made them

## Next Steps

Now that you understand the concepts, explore:

- [CLI commands](/docs/cli) for all operations
- [Web app guide](/docs/web-app) for browser-based management