/sys/namespaces

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

List namespaces

This endpoints lists all the namespaces.

Sample request

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

Sample response

{  "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.

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

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

Sample request

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

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

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

Sample request

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

Sample request

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

Sample request

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

Sample response

{  "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.

Sample request - current namespace

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

Sample response - current namespace

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

Sample request - X-Vault-Namespace

$ 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

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

Sample request - descendant of current namespace

$ 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

{    "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.

Sample payload - current namespace Non-Root

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

Sample request - current namespace Non-Root

$ 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

$ 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

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

Sample request - descendant namespace Non-Root

$ 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