»/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

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

Sample Response

["ns1/", "ns2/"]

["ns1/", "ns2/"]

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"
  }
}

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

$ 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"
  }
}

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

$ 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

$ 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

$ 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"
  }
}

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

$ 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>"
}

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

$ 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>"
}

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

$ 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_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>"
}

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

$ 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

$ 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>"
}

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

$ 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