mirror of
https://github.com/hashicorp/vault.git
synced 2025-08-22 15:11:07 +02:00
0660ea6fac
* Update README Let contributors know that docs will now be located in UDR * Add comments to each mdx doc Comment has been added to all mdx docs that are not partials * chore: added changelog changelog check failure * wip: removed changelog * Fix content errors * Doc spacing * Update website/content/docs/deploy/kubernetes/vso/helm.mdx Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com> --------- Co-authored-by: jonathanfrappier <92055993+jonathanfrappier@users.noreply.github.com> Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
290 lines
6.2 KiB
Plaintext
290 lines
6.2 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: /sys/namespaces - HTTP API
|
||
description: The `/sys/namespaces` endpoint is used manage namespaces in Vault.
|
||
---
|
||
|
||
> [!IMPORTANT]
|
||
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.
|
||
|
||
# `/sys/namespaces`
|
||
|
||
@include 'alerts/enterprise-only.mdx'
|
||
|
||
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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
-X LIST \
|
||
http://127.0.0.1:8200/v1/sys/namespaces
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"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.
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------------- |
|
||
| `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
|
||
|
||
```json
|
||
{
|
||
"custom_metadata": {
|
||
"foo": "abc",
|
||
"bar": "123"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ 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.
|
||
|
||
| Method | Path |
|
||
| :------- | :---------------------- |
|
||
| `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
|
||
|
||
```json
|
||
{
|
||
"custom_metadata": {
|
||
"foo": "abc",
|
||
"bar": "123"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ 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.
|
||
|
||
| Method | Path |
|
||
| :------- | :---------------------- |
|
||
| `DELETE` | `/sys/namespaces/:path` |
|
||
|
||
### Sample request
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/sys/namespaces/ns1
|
||
```
|
||
|
||
### Sample response
|
||
|
||
```json
|
||
{
|
||
"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](/vault/docs/concepts/namespace-api-lock#api-locked-response).
|
||
|
||
| Method | Path |
|
||
| :----- | :---------------------- |
|
||
| `POST` | `/sys/namespaces/api-lock/lock/:subpath` |
|
||
|
||
### Sample request - current namespace
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
http://127.0.0.1:8200/v1/sys/namespaces/api-lock/lock
|
||
```
|
||
|
||
### Sample response - current namespace
|
||
|
||
```json
|
||
{
|
||
"unlock_key": "<unlock key for current/ns/path>"
|
||
}
|
||
```
|
||
|
||
### Sample request - X-Vault-Namespace
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```json
|
||
{
|
||
"unlock_key": "<unlock key for some/path>"
|
||
}
|
||
```
|
||
|
||
### Sample request - descendant of current namespace
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```json
|
||
{
|
||
"unlock_key": "<unlock key for current/ns/path>"
|
||
}
|
||
```
|
||
|
||
### Sample request - current namespace Non-Root
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```shell-session
|
||
$ 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
|
||
|
||
```json
|
||
{
|
||
"unlock_key": "<unlock key for current/ns/path/some/descendant/subpath>"
|
||
}
|
||
```
|
||
|
||
### Sample request - descendant namespace Non-Root
|
||
|
||
```shell-session
|
||
$ 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
|
||
```
|