# Concepts

## Workspaces

A workspace holds your team's projects, environments, roles and members. The person who creates it is the **owner**. Everyone else joins by invitation.

## Environments

Environments are defined once per workspace and apply to every project in it, so `prod` means the same thing everywhere. A new workspace starts with `prod`. Each environment has two flags:

| Flag | Meaning |
|---|---|
| Production | Marks the environment as production. Shown in red, never allows personal overrides. |
| Allow personal overrides | Lets each user override values for themselves in this environment. |

When you add an environment, the Owner and Admin roles get `write` on it. Every other role gets `none`, unless you copy permissions from an existing environment.

## Projects

A **project** is usually one repository or one deployable app. It holds one set of values per environment: `shop` in `prod` has exactly one `DATABASE_URL`.

If two apps need different values for the same key, give each app its own project.

## Personal overrides and resolution

Every value is either a **team value** or a **personal override**:

| Source | Who sees it | Typical use |
|---|---|---|
| Shared | everyone with access to the environment, CI, syncs | `SENTRY_DSN`, `STRIPE_SECRET_KEY` |
| Personal | only you, only on environments that allow it | `DATABASE_URL=postgres://localhost/...` |

When you read an environment, your personal overrides win over the team value for the same key:

```
Shared[env]  →  Personal[env, you]
```

Example for `shop` in `dev`:

| Key | Shared | Yours | Result |
|---|---|---|---|
| `SENTRY_DSN` | `https://sentry...` | | `https://sentry...` (shared) |
| `DATABASE_URL` | `postgres://team` | `postgres://localhost` | `postgres://localhost` (personal) |

Resolved entries carry this as `source: "shared"` or `source: "personal"`.

- Writing a team value needs `write` on the environment. Overriding a value for yourself needs only `read`.
- Personal overrides are visible only to their owner. Admins can't see or reveal them.
- Service tokens, [syncs](/docs/syncs) and [webhooks](/docs/webhooks) never receive personal overrides. A deploy always gets the team's values.
- Production environments never allow personal overrides.

## Versions and deletion

Every write creates an immutable version. The last 30 versions of each key are kept, and any of them can be restored, which adds a new version. Deleted keys can be restored for 30 days.

## Syncs and webhooks

A **sync** pushes one environment of a project to a Vercel project or to GitHub Actions secrets after every change. See [Syncs](/docs/syncs).

A **webhook** sends a signed request to your URL, or a message to Slack, when secrets change or a sync finishes. See [Webhooks](/docs/webhooks).

## Audit log

Every create, update, rename, delete, reveal, pull and permission change is recorded with the actor, time, IP address and key name. Values are never written to the log. Entries are kept for 90 days.