vault/website/content/api-docs/system/namespaces.mdx

---
layout: api
page_title: /sys/namespaces - HTTP API
description: The `/sys/namespaces` endpoint is used manage namespaces in Vault.
---

# `/sys/namespaces`

@include 'alerts/enterprise-only.mdx'

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](/vault/docs/concepts/namespace-api-lock#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
```