Skip to main content
Version: Development

/sys/namespaces

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

List namespaces​

This endpoints lists all the namespaces.

MethodPath
LIST/sys/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.

MethodPath
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.
  • seal (string: "") - An optional seal config document (JSON or HCL) to create a sealable namespace

Sample payload​

{
  "custom_metadata": {
    "foo": "abc",
    "bar": "123"
  },
  "seal": "seal \"shamir\" {\n    shares = 5\n    threshold = 3\n}"
}

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.

MethodPath
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​

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

MethodPath
DELETE/sys/namespaces/:path

Sample request​

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

Delete sealed namespace​

info

Note that this requires the sudo capability and will not clean up external resources via lease deletion like standard namespace deletion does. Prefer the standard DELETE /sys/namespaces/:path endpoint unless the namespace is irrecoverable due to lost seal keys.

This endpoint deletes a sealed namespace at the specified path.

MethodPath
DELETE/sys/namespaces/:path/delete-sealed

Parameters​

  • force (bool: false) - if set to true, will also recursively delete any child namespaces.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/namespaces/ns1/delete-sealed?force=true

Read namespace information​

This endpoint gets the metadata for the given namespace path.

MethodPath
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/",
  "custom_metadata": {
    "foo": "abc",
    "bar": "123"
  }
}

Read namespace seal status (sealable namespaces only)​

This endpoint gets the seal status for the given sealable namespace path.

MethodPath
GET/sys/namespaces/:path/seal-status

Sample request​

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

Sample response​

{
  "initialized": true,
  "n": 5,
  "nonce": "",
  "progress": 0,
  "sealed": false,
  "t": 3,
  "type": "shamir"
}

Unseal a namespace (sealable namespaces only)​

This endpoint unseals the given sealable namespace.

MethodPath
PUT/sys/namespaces/:path/unseal

Sample payload​

{
  "key": "...",
  "reset": false,
}

Sample request​

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

Sample response​

{
  "initialized": true,
  "n": 5,
  "nonce": "",
  "progress": 1,
  "sealed": true,
  "t": 3,
  "type": "shamir"
}

Seal a namespace (sealable namespaces only)​

This endpoint seals the given sealable namespace.

MethodPath
PUT/sys/namespaces/:path/seal

Sample request​

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