Skip to main content
Vault Namespaces provide isolated, virtual Vault environments within a single cluster. They enable multi-tenancy by letting you delegate administration, manage policies, auth methods, secrets engines, tokens, and identities per namespace—without running multiple clusters or storage backends.
Vault Namespaces are available only in Vault Enterprise.
See Enterprise Namespaces Documentation for more details.

​
What Is a Namespace?

A Vault namespace is a child environment inside the root namespace. Each namespace acts like a standalone Vault, offering:
  • Fully isolated policies, auth methods, and secrets engines
  • Delegation of administration to namespace-specific admins
  • Centralized cluster management (storage backend, audit devices, upgrades)
  • Hierarchical namespaces, with support for nested child namespaces
  • Namespace-scoped tokens (valid only within the issuing namespace)
The image is a slide explaining namespaces, highlighting that the default namespace is 'root', they are hierarchical, and tokens are valid in a single namespace. It includes a Vault certification badge and a cartoon character.

​
Namespace Hierarchy

Namespaces are organized in a tree structure under the root. You can enable auth methods, secrets engines, and policies at any level—paths and ACLs are always relative to the namespace where they’re defined. This makes policy reuse straightforward.
The image illustrates a hierarchical structure of namespaces in a Vault system, showing how each namespace can have its own authentication methods, secrets engine, and policies.
Each namespace can spawn child namespaces indefinitely:
The image is a diagram illustrating a hierarchy of namespaces, showing how they are organized with elements like Auth Method, Secrets Engine, and Policies. It includes a "Vault Certified Operations Professional" badge and a cartoon character at the bottom right.

​
Assigning Namespaces to Teams

In a production Vault cluster, you might create separate namespaces for Cloud, Engineering, and Developer teams. Each namespace starts empty—no auth methods or engines are enabled by default.
The image illustrates a "Production Vault Cluster" with three namespaces: Cloud-Team, Engineering, and Developer, each containing "Secrets Engines," "Auth Methods," and "Policies."
Teams then manage only their assigned namespace:
The image illustrates the assignment of namespaces within a production vault cluster, showing different teams (Cloud Engineers, DevOps Engineers, Core Developers) and their respective namespaces with components like Secrets Engines, Auth Methods, and Policies.

​
Administrative Delegation

Vault engineers handle cluster-wide tasks (storage backend, root namespace, upgrades). Namespace admins (e.g., developers) gain autonomy to configure auth methods, secrets engines, policies, and tokens—without tickets.
The image illustrates administrative delegation in a Vault system, showing different namespaces and responsibilities for developers and engineers. It highlights the roles of Developer Namespace Admins and Vault Engineers in managing secrets engines, policies, and cluster components.

​
Authenticating to Namespaces

Users authenticate either at the root or directly into child namespaces—wherever relevant auth methods are enabled.
The image illustrates a diagram of authenticating to namespaces, showing a root namespace with cloud-team and engineering namespaces, each using different authentication methods (AWS, Azure, OIDC). A person is depicted using a laptop, and there's a Vault certification badge.
If a child namespace has its own auth method enabled (e.g., userpass), users can log in directly there:
The image illustrates a diagram of authenticating to namespaces, showing different authentication methods (AWS, Azure, Userpass, OIDC) within a root namespace structure. It also includes a person using a laptop, with a badge indicating "Vault Certified Operations Professional."

​
Common Namespace CLI Commands

CommandDescriptionExample
Create namespaceCreate a new namespacevault namespace create <namespace>
List namespacesList all existing namespacesvault namespace list
Delete namespaceRemove an existing namespacevault namespace delete <namespace>
$ vault namespace create cloud-team
Key     Value
---     -----
id      n57y6
path    cloud-team/

$ vault namespace list
$ vault namespace delete cloud-team

​
Using an Environment Variable

Set VAULT_NAMESPACE so all CLI requests default to that namespace: 
export VAULT_NAMESPACE=cloud-team
vault kv get kv/data/sql/prod

​
Using the -namespace Flag

Override the namespace for a single command: 
vault kv get -namespace=cloud-team kv/data/sql/prod

​
Nested Namespace Example

Combine both methods to target child namespaces: 
export VAULT_NAMESPACE=cloud-team
vault kv get -namespace=team-one kv/data/sql/prod

​
Using Namespaces in the API

You can specify namespaces either via a header or in the URL path.
MethodDescription
Header approachSend X-Vault-Namespace in the request
URL path approachPrefix the endpoint with <namespace>/

​
1. X-Vault-Namespace Header

curl \
  --header "X-Vault-Token: hvs.a83b50ed2aa548212" \
  --header "X-Vault-Namespace: development/" \
  --request GET \
  https://vault.example.com:8200/v1/kv/data/sql/prod

​
2. Namespace in the URL Path

curl \
  --header "X-Vault-Token: hvs.CAESIA7Y-LwSxnE926onQwdxIUf7" \
  --request GET \
  https://vault.example.com:8200/v1/development/kv/data/sql/prod
For nested namespaces, extend the path:
v1/development/team-one/kv/data/sql/prod

​
Writing Policies for Namespaces

Policy paths are relative to their namespace: Inside cloud-team: 
path "database/creds/prod-db" {
  capabilities = ["read"]
}
From the root namespace to access a secret in cloud-team: 
path "cloud-team/database/creds/prod-db" {
  capabilities = ["read"]
}
Include further segments for deeper hierarchies.

​
Authenticating via the UI

When signing in, specify your namespace (default is root), choose the auth method, and enter your credentials:
The image shows a login interface for "Sign in to Vault" with fields for namespace, method, username, and password. It includes annotations with arrows and a badge labeled "Vault Certified Operations Professional."

​
Conclusion

Vault Namespaces streamline multi-tenant deployments, enabling delegated management and isolated environments within a single cluster. Master the CLI, API, and UI workflows for effective namespace administration and be prepared for your Vault certification.

​
References

Watch Video