# /sys/namespaces

The `/sys/namespaces` endpoint is used manage namespaces in Vault.

### List namespaces

This endpoints lists all the namespaces.

| Method | Path              |
| ------ | ----------------- |
| `LIST` | `/sys/namespaces` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    -X LIST \
    http://127.0.0.1:8200/v1/sys/namespaces
```

#### Sample response

```json
{
  "data": {
    "key_info": {
      "bar/": {
        "custom_metadata": {},
        "id": "HWmNL",
        "path": "bar/"
      },
      "foo/": {
        "custom_metadata": {},
        "id": "5q39x",
        "path": "foo/"
      }
    },
    "keys": [
      "bar/",
      "foo/"
    ]
  }
}
```

### Create namespace

This endpoint creates a namespace at the given path.

| Method | Path                    |
| ------ | ----------------------- |
| `POST` | `/sys/namespaces/:path` |

#### Parameters

* `path` `(string: <required>)` – Specifies the path where the namespace will be created.
* `custom_metadata` `(map<string|string>: nil)` - A map of arbitrary string to string valued user-provided metadata meant to describe the namespace.

#### Sample payload

```json
{
  "custom_metadata": {
    "foo": "abc",
    "bar": "123"
  }
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/namespaces/ns1
```

### Patch namespace

This endpoint patches an existing namespace at the specified path.

| Method  | Path                    |
| ------- | ----------------------- |
| `PATCH` | `/sys/namespaces/:path` |

#### Parameters

* `path` `(string: <required>)` – Specifies the path of the existing namespace.
* `custom_metadata` `(map<string|string>: nil)` - A map of arbitrary string to string valued user-provided metadata meant to describe the namespace.

#### Sample payload

```json
{
  "custom_metadata": {
    "foo": "abc",
    "bar": "123"
  }
}
```

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --header "Content-Type: application/merge-patch+json"
    --request PATCH \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/namespaces/ns1
```

### Delete namespace

This endpoint deletes a namespace at the specified path.

| Method   | Path                    |
| -------- | ----------------------- |
| `DELETE` | `/sys/namespaces/:path` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/namespaces/ns1
```

### Read namespace information

This endpoint gets the metadata for the given namespace path.

| Method | Path                    |
| ------ | ----------------------- |
| `GET`  | `/sys/namespaces/:path` |

#### Sample request

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/namespaces/ns1
```

#### Sample response

```json
{
  "id": "gsudj",
  "path": "ns1/",
  "custom_metadata": {
    "foo": "abc",
    "bar": "123"
  }
}
```

### Lock namespace

This endpoint locks the API for the current namespace path or optional subpath. The behavior when interacting with Vault from a locked namespace is described in API Locked Response.

| Method | Path                                     |
| ------ | ---------------------------------------- |
| `POST` | `/sys/namespaces/api-lock/lock/:subpath` |

#### Sample request - current namespace

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock
```

#### Sample response - current namespace

```json
{
    "unlock_key": "<unlock key for current/ns/path>"
}
```

#### Sample request - X-Vault-Namespace

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --header "X-Vault-Namespace: some/path
    --request POST \
    http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock
```

#### Sample response - X-Vault-Namespace

```json
{
    "unlock_key": "<unlock key for some/path>"
}
```

#### Sample request - descendant of current namespace

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock/some/descendant/subpath
```

#### Sample response - descendant of current namespace

```json
{
    "unlock_key": "<unlock key for current/ns/path/some/descendant/subpath>"
}
```

### Unlock namespace

This endpoint unlocks the api for the current namespace path or optional subpath.

| Method | Path                                       |
| ------ | ------------------------------------------ |
| `POST` | `/sys/namespaces/api-lock/unlock/:subpath` |

#### Sample payload - current namespace Non-Root

```json
{
  "unlock_key": "<unlock key for current/ns/path>"
}
```

#### Sample request - current namespace Non-Root

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/namespaces/api-lock/unlock
```

#### Sample request - current namespace root

```shell-session
$ curl \
    --header "X-Vault-Token: <some root token>" \
    --request POST \
    http://127.0.0.1:8200/v1/sys/namespaces/api-lock/unlock
```

#### Sample payload - descendant namespace Non-Root

```json
{
  "unlock_key": "<unlock key for current/ns/path/some/descendant/subpath>"
}
```

#### Sample request - descendant namespace Non-Root

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/namespaces/api-lock/unlock/some/descendant/path
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/api/system-backend/sys-namespaces.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.