• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Vault Home

API

Skip to main content
  • API
  • Client Libraries
  • Related Tools

    • Overview
    • /sys/audit
    • /sys/audit-hash
    • /sys/auth
    • /sys/capabilities
    • /sys/capabilities-accessor
    • /sys/capabilities-self
    • /sys/config/auditing
    • /sys/config/control-group
    • /sys/config/cors
    • /sys/config/reload
    • /sys/config/state
    • /sys/config/ui
    • /sys/control-group
    • /sys/generate-recovery-token
    • /sys/generate-root
    • /sys/health
    • /sys/host-info
    • /sys/in-flight-req
    • /sys/init
    • /sys/internal/counters
    • /sys/internal/specs/openapi
    • /sys/internal/ui/feature-flags
    • /sys/internal/ui/mounts
    • /sys/internal/ui/namespaces
    • /sys/internal/ui/resultant-acl
    • /sys/key-status
    • /sys/ha-status
    • /sys/leader
    • /sys/leases
    • /sys/license/status
    • /sys/loggers
    • /sys/managed-keys
      ENTENT
    • /sys/metrics
    • /sys/monitor
    • /sys/mounts
    • /sys/namespaces
    • /sys/plugins/reload/backend
    • /sys/plugins/catalog
    • /sys/policy
    • /sys/policies
    • /sys/policies/password
    • /sys/pprof
    • /sys/quotas/config
    • /sys/quotas/rate-limit
    • /sys/quotas/lease-count
    • /sys/raw
    • /sys/rekey
    • /sys/rekey-recovery-key
    • /sys/remount
    • /sys/rotate
    • /sys/rotate/config
    • /sys/seal
    • /sys/seal-status
    • /sys/sealwrap/rewrap
    • /sys/step-down
    • /sys/tools
    • /sys/unseal
    • /sys/version-history
    • /sys/wrapping/lookup
    • /sys/wrapping/rewrap
    • /sys/wrapping/unwrap
    • /sys/wrapping/wrap

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. API
  4. System Backend
  5. /sys/namespaces
  • Vault
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x
  • v1.7.x
  • v1.6.x
  • v1.5.x
  • v1.4.x

»/sys/namespaces

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

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.

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.

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

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

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.

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

MethodPath
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
Edit this page on GitHub

On this page

  1. /sys/namespaces
  2. List Namespaces
  3. Create Namespace
  4. Patch Namespace
  5. Delete Namespace
  6. Read Namespace Information
  7. Lock Namespace
  8. Unlock Namespace
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)