Namespaces

A Vault Namespace is a logical grouping mechanism within Vault that allows the separation of policies, authentication methods, secrets engines, and other configurations. Essentially, it divides a Vault deployment into different environments or organisational units, providing isolation and control over access and operations. Namespaces allow teams or departments to manage their secrets and configurations independently within a shared Vault infrastructure, improving security and governance.

Create a namespace at the path education/ :

CLI

vault namespace create education/

API

curl --location --request POST 'https://127.0.0.1:8200/v1/sys/namespaces/education'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation

Response

200

{
    "request_id": "1ff6c7cd-60e4-a2e7-2fbb-02cbf6eb3694",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "custom_metadata": {},
        "id": "education",
        "path": "education/"
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

400

{
  "error": "Invalid request"
}

List all namespaces:

CLI

vault namespace list

API

curl --location 'https://127.0.0.1:8200/v1/sys/namespaces?list=true'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation

Response

200

{
    "request_id": "9afc7d71-0785-360f-f73e-da6e324d1501",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "education/"
        ]
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

400

{
  "error": "Invalid request"
}

Lookup the namespace information at path education/ :

CLI

vault namespace lookup education/

API

curl --location 'https://127.0.0.1:8200/v1/sys/namespaces/education'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation

Response

200

{
    "request_id": "6ea4fec0-3909-fa49-b467-66b1fee7f0be",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "custom_metadata": {},
        "id": "education",
        "path": "education/"
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

400

{
  "error": "Invalid request"
}

Delete the namespace at path education/ :

CLI

vault namespace delete education/

API

curl --location --request DELETE 'https://127.0.0.1:8200/v1/sys/namespaces/education'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation

Response

200

{
    "request_id": "8c6d9680-6d63-6b73-52df-c22f30cba450",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": null,
    "wrap_info": null,
    "warnings": [
        "child namespaces are not deleted"
    ],
    "auth": null
}

400

{
  "error": "Invalid request"
}

Accessing a namespace:

Users can access namespaces by specifying the namespace in the Vault CLI commands or API requests using the -namespace flag or parameter.

CLI

vault secrets list -namespace=education

API

curl --location 'https://127.0.0.1:8200/v1/sys/mounts'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation
X-Vault-Namespace	education

Response

200

{
    "request_id": "cf35f702-70a9-b599-b77a-8d731ae0b03a",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "cubbyhole/": {},
        "identity/": {},
        "kv/": {},
        "sys/": {}
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

400

{
  "error": "Invalid request"
}

Managing policies within a namespace:

Create a policy specific to the "education" namespace:

CLI

vault policy write education-policy policy.hcl -namespace=education

API

curl --location --request POST 'https://127.0.0.1:8200/v1/sys/policy/education-policy'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation
X-Vault-Namespace	education

Body

{
  "policy": "{\"path\":{\"*\":{\"capabilities\":[\"sudo\",\"read\",\"create\",\"update\",\"patch\",\"list\",\"delete\"]}}}"
}

Response

200

{
    "request_id": "8e086eea-49cf-8482-e0b7-e8039b8653f1",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "name": "education-policy",
        "rules": "{\"path\":{\"*\":{\"capabilities\":[\"sudo\",\"read\",\"create\",\"update\",\"patch\",\"list\",\"delete\"]}}}"
    },
    "wrap_info": null,
    "warnings": null,
    "auth": null
}

400

{
  "error": "Invalid request"
}

Using secrets engines:

Mount a secrets engine named "kv" within the "education" namespace:

CLI

vault secrets enable kv -namespace=education

API

curl --location --request POST 'https://127.0.0.1:8200/v1/sys/mounts/kv'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation
X-Vault-Namespace	education

Body

{
    "type":"kv"
}

Response

204

No Content

400

{
  "error": "Invalid request"
}

Creating secrets in KV secrets engine:

You can write a secret to the KV secrets engine. For example, let's add a username and password:

CLI

vault kv put kv/my-secret username="example_user" password="example_password" -namespace=education

API

curl --location --request POST 'https://127.0.0.1:8200/v1/kv/data/my-secret'

Headers

Name	Value
X-Vault-token	JWT Login - Vault API Documentation
X-Vault-Namespace	education

Body

{
    "username":"example_user",
    "password":"example_password"
}

Response

204

No Content

400

{
  "error": "Invalid request"
}