# Access & key grants

Access to an environment's secrets is **cryptographic**: a principal can decrypt an environment
if and only if it holds a key grant — a copy of the environment's data key (DEK) wrapped to its
public key — and the matching private key.

## Granting access

When a principal is granted access, the granting client:

1. Unwraps its own copy of the environment DEK with its private key.
2. Re-wraps that DEK to the target principal's public key.
3. Uploads the new wrapped blob as a key grant.

All of this happens on the granter's client. The server stores the wrapped blob but never sees
the DEK in the clear. Because wrapping needs the target's public key, a user must have completed
[key setup](/docs/guides/web-app) before they can be granted access.

In the web dashboard this is a tick in an application's **Access** tab (or the **Access**
panel on a single environment); with the CLI it is `seekrit grant`.

The **Access** tab lists every member and service token against every environment of the
application, so "who can read production?" and "what can this person read?" are both one glance.
A member's **All + future** switch grants every environment at once — branches and composed
groups included — and records a standing policy: any environment added to the application later
must be wrapped for that member too, by whoever creates it. Switching it off ends the policy
only; the keys they already hold stay until you untick them.

![An application's Access tab: a table with a member and a service token down the side and the development, staging and production environments across the top, a tick in each cell where that principal can decrypt, and an All + future switch on the member's row](https://seekrit.dev/screenshots/original/dashboard-app-access.webp)

*The Access tab. Each tick is one environment's key wrapped to that member or token; the switch shares every environment and keeps future ones included.*

The **Members** page shows the same grants per person: an **Access** summary on every row that
opens everything that member can decrypt, across applications and shared groups.

![The Access panel listing a service token and a member who hold the environment key, each with a tick, above a grant selector and a link to the application's Access tab](https://seekrit.dev/screenshots/original/dashboard-key-access.webp)

*The Access panel: every principal holding a wrapped copy of this environment's data key — here one service token and one member — each with the tick that revokes it.*

## Roles vs. grants

Two independent mechanisms govern what someone can do:

- **Role** (`owner` / `admin` / `member`) gates the management API — who may create environments,
  mint tokens, manage grants, invite members, or read the audit trail.
- **Key grant** gates decryption — who can actually read secret values.

A member with no key grant for an environment can see that the environment exists (if their role
allows) but cannot decrypt anything in it.

Service tokens carry a role too: **member** (the default — a runtime credential whose real power
is its key grants) or **admin** (an org-scoped token that also passes the management API, so
automation and [AI agents](/docs/guides/ai-agents) can provision structure headlessly). A token is
never `owner`. Only an admin caller can mint an admin token, and granting any token decryption
still requires the caller to already hold that environment's key — so capability never escalates
itself.

### A third mechanism: approval

Role and grant both answer "may this principal act at all". [Approval
workflows](/docs/guides/approvals) answer a different question — "may *this
change* land" — and they compose with the other two rather than replacing
either. A protected environment queues every write, including one from a
principal whose role and key grant would otherwise have been enough.

The useful property is that reviewing needs **neither**: a change request holds
ciphertext, so an admin with no key grant for the environment can approve a
change to it without ever being able to read what is in it. Signing off on
production and being able to read production stay separate capabilities.

## Revocation vs. rotation

These solve different problems, and both matter.

**Revocation** deletes a principal's key grant. It immediately stops that principal from fetching
the DEK again. Use it when someone leaves or a token is retired.

> **Warning:** Revoking a grant does not change the DEK. A principal that already fetched and cached the DEK
>   could still decrypt values it captured. To truly cut off access to existing secrets, rotate the
>   key.

**Key rotation** replaces the environment's DEK entirely: generate a new DEK, re-encrypt every
secret with it, and re-wrap it for the remaining principals. After rotation, any previously
cached copy of the old DEK is useless.

Revocation is instant and cheap; rotation is the complete, heavier operation. A typical response
to a departing teammate is to revoke immediately, then rotate.

> **Note:** Two different things are called rotation. **Key** rotation, above, replaces the
>   key an environment's secrets are encrypted *under* — it defeats a cached DEK.
>   [**Secret** rotation](/docs/concepts/rotation) replaces a secret's *value* on a
>   schedule — it defeats a leaked credential. A departing teammate calls for the
>   first; a stale database password calls for the second.

## Auditing access changes

Every grant and revocation is recorded in the [audit trail](/docs/concepts/security#audit-trail)
with the actor and target principal, so access changes are always attributable.
