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 before they can be granted access.

In the web dashboard this is the Key access panel on an environment; with the CLI it is seekrit grant.

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

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.

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.

Auditing access changes

Every grant and revocation is recorded in the audit trail with the actor and target principal, so access changes are always attributable.