Namespace access (people & teams)
Give one person or team read or write access to a single namespace, without granting them the whole space — how grants combine with roles, and why they can only ever add access.
Access policies govern machines. Namespace grants govern people: they let you give one colleague — or a whole team — access to a single namespace, without making them an administrator of everything.
Namespace grants require the Team, Business, or Enterprise plan. They only apply in an organization space: a personal Developer space has no other principals to grant to, so the feature does nothing there.
The problem it solves#
Before grants, namespace access was all-or-nothing at the space level. A data engineer who needed
the connection strings in data/etl had to be given secrets:secret:read across the whole
organization — which also handed them production payment keys.
A grant is narrower: this person, this namespace, this level.
The three levels#
| Level | What the grantee can do |
|---|---|
| View | See the namespace's secrets — names, metadata and history — and browse its folder tree. Never a value. |
| Read | Everything View allows, plus reveal and copy every secret's value |
| Write | Everything Read allows, plus create, update, rename and delete secrets under it |
Each level contains the ones above it — you never need to grant two. Use View for a reviewer or auditor who must see what exists without being able to read it.
Granting access#
Open the namespace → Access panel → Add access. Choose a User or a Team, pick the principal, and select the level.
- Managing grants requires
secrets:namespace:manage— the same permission that lets you create or rename a namespace. - The principal must belong to your organization.
- A user or team can hold at most one grant per namespace; change the level by revoking and re-adding.
- Granting to a team covers everyone with an active membership in it, so access follows people as they join and leave the team — nothing to clean up per person.
Both granting and revoking are recorded in the audit log and retained on the extended schedule. Revoking is immediate and complete — grants keep no history once removed.
What grants can and cannot do#
Grants are evaluated after the normal permission check, never instead of it. If someone already has access through their role, a grant changes nothing; if they don't, a matching grant may allow the action. There is no "deny" grant, so a grant can never be used to take access away from an administrator or lock anyone out.
A grant covers the contents of a namespace, not the namespace itself. Someone with a Write grant can freely manage secrets and folders inside it, but cannot:
- rename, archive, or rotate the encryption key of the namespace,
- create environments or other namespaces,
- create machine identities, issue API keys, or attach policies.
Those remain space-level actions, gated by the secrets:* permissions in
Paths, plans & roles. The reasoning is that managing a namespace
is a structural act with blast radius beyond the secrets inside it.
If the plan is downgraded below Team, grants stop being consulted — access falls back to roles alone. The rows are not deleted, so they take effect again on re-upgrade.
Grants vs. policies#
| Namespace grants | Access policies | |
|---|---|---|
| Applies to | People and teams | Machine identities |
| Scope | One namespace | Path patterns across projects and environments |
| Levels | Read / Write | read · write · delete · list · rotate |
| Used from | The console | The API, CLI and CI |
A pipeline never uses a grant, and a person never uses a policy. If a colleague reports they can read a secret in the console but their pipeline gets a 403, the pipeline needs a policy — the grant does not apply to it.