/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

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

Sample response

["ns1/", "ns2/"]

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.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    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

$ 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

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

Sample response

{
  "id": "gsudj",
  "path": "ns1/"
}

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

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

Method	Path
`POST`	`/sys/namespaces/api-lock/unlock/: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