> For the complete documentation index, see [llms.txt](https://docs.enclaive.cloud/vault/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.enclaive.cloud/vault/tutorials/use-cases/namespaces.md).

# 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/` :

{% tabs %}
{% tab title="CLI" %}

```
vault namespace create education/
```

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name          | Value                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## List all namespaces:

{% tabs %}
{% tab title="CLI" %}

```
vault namespace list
```

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name          | Value                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |

**Response**

{% tabs %}
{% tab title="200" %}

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

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Lookup the namespace information at path `education/` :

{% tabs %}
{% tab title="CLI" %}

```
vault namespace lookup education/
```

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name          | Value                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Delete the namespace at path  `education/` :

{% tabs %}
{% tab title="CLI" %}

```
vault namespace delete education/
```

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name          | Value                                                                                                                        |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="CLI" %}

```
vault secrets list -namespace=education
```

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name              | Value                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token     | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |
| X-Vault-Namespace | `education`                                                                                                                  |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Managing policies within a namespace: 

Create a policy specific to the "education" namespace:

{% tabs %}
{% tab title="CLI" %}

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

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name              | Value                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token     | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |
| X-Vault-Namespace | `education`                                                                                                                  |

**Body**

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

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
    "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
}
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## Using secrets engines:

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

{% tabs %}
{% tab title="CLI" %}

```
vault secrets enable kv -namespace=education
```

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name              | Value                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token     | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |
| X-Vault-Namespace | `education`                                                                                                                  |

**Body**

```json
{
    "type":"kv"
}
```

**Response**

{% tabs %}
{% tab title="204" %}

```json
No Content
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}

## 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:

{% tabs %}
{% tab title="CLI" %}

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

{% endtab %}

{% tab title="API" %}

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

{% endtab %}
{% endtabs %}

**Headers**

| Name              | Value                                                                                                                        |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| X-Vault-token     | [JWT Login - Vault API Documentation](https://docs.enclaive.cloud/vault/api/auth-methods/jwt-oidc-auth-method-api#jwt-login) |
| X-Vault-Namespace | `education`                                                                                                                  |

**Body**

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

**Response**

{% tabs %}
{% tab title="204" %}

```json
No Content
```

{% endtab %}

{% tab title="400" %}

```json
{
  "error": "Invalid request"
}
```

{% endtab %}
{% endtabs %}