mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-11-02 11:38:02 +00:00
VAULT-23051: Documenting API Endpoints (#24845)
* api documentation changes * document management endpoints * add new website page to the navigation * include explanation message retrieval from namespaces up to root namespace * added clarification statement to the create and update operations documentation * fixed inconsistency in sample request * Apply suggestions from code review Co-authored-by: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com> --------- Co-authored-by: Jonathan Frappier <92055993+jonathanfrappier@users.noreply.github.com>
This commit is contained in:
Marc Boudreau
242
website/content/api-docs/system/config-ui-custom-messages.mdx
Normal file
242
website/content/api-docs/system/config-ui-custom-messages.mdx
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/config/ui/custom-messages - HTTP API
|
||||
description: The '/sys/config/ui/custom-messages' endpoint configures the custom messages that the UI displays prior to and immediately following login operations.
|
||||
---
|
||||
|
||||
# `/sys/config/ui/custom-messages`
|
||||
|
||||
The `/sys/config/ui/custom-messages` endpoint is used to list, create, read, update, or delete custom messages.
|
||||
|
||||
## List custom messages
|
||||
|
||||
This endpoint returns a list of all custom messages that exist.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :-------------------------------- |
|
||||
| `LIST` | `/sys/config/ui/custom-messages/` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `active` `(bool: <optional>)` - A flag indicating whether to only include custom messages whose active property is set to the value specified in the results. If this parameter is omitted, the results include both active and inactive custom messages.
|
||||
|
||||
- `authenticated` `(bool: <optional>)` - A flag indicating whether to only include custom messages whose authenticated property is set to the value specified in the results. If this parameter is omitted, the results include both authenticated and unauthenticated custom messages.
|
||||
|
||||
- `type` `(string: <optional>)` - A flag that can only be set to either `banner` or `modal`. It indicates whether to only include custom messages whose type property is set to the value specified in the results. If this parameter is omitted, the results include both types of custom messages.
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl --header "X-Vault-Token: ..." \
|
||||
--request LIST \
|
||||
http://127.0.0.1:8200/v1/sys/config/ui/custom-messages?active=true&authenticated=false&type=modal
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"key_info": {
|
||||
"01234567-89ab-cdef-0123-456789abcdef": {
|
||||
"title": "Post-login Advisory",
|
||||
"type": "modal",
|
||||
"authenticated": false,
|
||||
"start_time": "2024-01-01T00:00:00.000000000Z",
|
||||
"end_time": null
|
||||
}
|
||||
},
|
||||
"keys": [
|
||||
"01234567-89ab-cdef-0123-456789abcdef"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Create custom message
|
||||
|
||||
This endpoint allows the creation of a new custom message. Vault allows up to 100 custom messages
|
||||
per namespace. If this endpoint is called to create a custom message when the maximum number of
|
||||
custom messages already exists, an error will be returned.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :-------------------------------- |
|
||||
| `POST` | `/sys/config/ui/custom-messages/` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `title` `(string: <required>)` - The title of the custom message.
|
||||
|
||||
- `authenticated` `(bool: <optional>)` - A flag indicating whether the custom message is displayed post-login (`true`) or pre-login (`false`). If this parameter is omitted, the custom message is created as post-login. Pre-login messages may be retrieved by anonymous clients, as such their content should not contain any sensitive information.
|
||||
|
||||
- `type` `(string: <optional>)` - The type of the custom message. Must be either `banner` or `modal`. If this parameter is omitted, the custom message type is set to `banner`.
|
||||
|
||||
- `message` `(string: <required>)` - The base64 encoded message body of the custom message.
|
||||
|
||||
- `link` `(Map: <optional>)` - A link object that contains a single property. The property key is the link title and its value is the URL.
|
||||
|
||||
- `options` `(Map: <optional>)` - A map of custom UI properties to set for the custom message.
|
||||
|
||||
- `start_time` `(string: <required>)` - A RFC3339 formatted timestamp that marks the beginning of the custom message's active period.
|
||||
|
||||
- `end_time` `(string: <optional>)` - A RFC3339 formatted timestamp that marks the end of the custom message's active period. If no end time is provided, the custom message's active period never ends.
|
||||
|
||||
### Sample payload
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Post-login Advisory",
|
||||
"authenticated": true,
|
||||
"type": "modal",
|
||||
"message": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3VyYWJpdHVyIG51bGxhIGF1Z3VlLCBwbGFjZXJhdCBxdWlzIHJpc3VzIGJsYW5kaXQsIG1vbGVzdGllIGltcGVyZGlldCBtYXNzYS4gU2VkIGJsYW5kaXQgcnV0cnVtIG9kaW8gcXVpcyB2YXJpdXMuIEZ1c2NlIHB1cnVzIG9yY2ksIG1heGltdXMgYWMgbGliZXJvLgo=",
|
||||
"start_time": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl --header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json
|
||||
http://127.0.0.1:8200/v1/sys/config/ui/custom-messages
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
||||
"active": true,
|
||||
"start_time": "2023-10-15T02:36:43.986212308Z",
|
||||
"end_time": null,
|
||||
"type": "modal",
|
||||
"authenticated": false,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Read custom message
|
||||
|
||||
This endpoint returns the properties of a specific custom message.
|
||||
|
||||
| Method | |
|
||||
| :----- | :----------------------------------- |
|
||||
| `GET` | `/sys/config/ui/custom-messages/:id` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `id` `(string: <required>)` - The unique ID assigned to the custom message at creation time.
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl --header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/config/ui/custom-messages/01234567-89ab-cdef-0123-456789abcdef
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"id": "01234567-89ab-cdef-0123-456789abcdef",
|
||||
"title": "Pre-login Advisory",
|
||||
"active": true,
|
||||
"authenticated": false,
|
||||
"type": "banner",
|
||||
"message": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3VyYWJpdHVyIG51bGxhIGF1Z3VlLCBwbGFjZXJhdCBxdWlzIHJpc3VzIGJsYW5kaXQsIG1vbGVzdGllIGltcGVyZGlldCBtYXNzYS4gU2VkIGJsYW5kaXQgcnV0cnVtIG9kaW8gcXVpcyB2YXJpdXMuIEZ1c2NlIHB1cnVzIG9yY2ksIG1heGltdXMgYWMgbGliZXJvLgo.",
|
||||
"link": {
|
||||
"click here": "https://www.learnmore.com",
|
||||
},
|
||||
"options": {},
|
||||
"start_time": "2018-03-22T02:24:06.945319214Z",
|
||||
"end_time": null,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Update custom message
|
||||
|
||||
This endpoint updates the properties of a specific custom message.
|
||||
|
||||
| Method | |
|
||||
| :----- | :----------------------------------- |
|
||||
| `POST` | `/sys/config/ui/custom-messages/:id` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `id` `(string: <required>)` - The unique ID assigned to the custom message at creation time.
|
||||
|
||||
- `title` `(string: <required>)` - The title of the custom message.
|
||||
|
||||
- `authenticated` `(bool: <optional>)` - A flag indicating whether the custom message is displayed post-login (`true`) or pre-login (`false`). If this parameter is omitted, the custom message is created as post-login. Pre-login messages may be retrieved by anonymous clients, as such their content should not contain any sensitive information.
|
||||
|
||||
- `type` `(string: <optional>)` - The type of the custom message. Must be either `banner` or `modal`. If this parameter is omitted, the custom message type is set to `banner`.
|
||||
|
||||
- `message` `(string: <required>)` - The base64 encoded message body of the custom message.
|
||||
|
||||
- `link` `(Map: <optional>)` - A link object that contains a single property. The property key is the link title and its value is the URL.
|
||||
|
||||
- `options` `(Map: <optional>)` - A map of custom UI properties to set for the custom message.
|
||||
|
||||
- `start_time` `(string: <required>)` - A RFC3339 formatted timestamp that marks the beginning of the custom message's active period.
|
||||
|
||||
- `end_time` `(string: <optional>)` - A RFC3339 formatted timestamp that marks the end of the custom message's active period. If no end time is provided, the custom message's active period never ends.
|
||||
|
||||
### Sample payload
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Pre-login Advisory",
|
||||
"authenticated": false,
|
||||
"type": "modal",
|
||||
"message": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3VyYWJpdHVyIG51bGxhIGF1Z3VlLCBwbGFjZXJhdCBxdWlzIHJpc3VzIGJsYW5kaXQsIG1vbGVzdGllIGltcGVyZGlldCBtYXNzYS4gU2VkIGJsYW5kaXQgcnV0cnVtIG9kaW8gcXVpcyB2YXJpdXMuIEZ1c2NlIHB1cnVzIG9yY2ksIG1heGltdXMgYWMgbGliZXJvLgo=",
|
||||
"start_time": "2024-01-01T00:00:00.000Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl --header "X-Vault-Token: ..." \
|
||||
--request POST \
|
||||
--data @payload.json
|
||||
http://127.0.0.1:8200/v1/sys/config/ui/custom-messages/01234567-89ab-cdef-0123-456789abcdef
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"active": true,
|
||||
"title": "Pre-login Advisory",
|
||||
"start_time": "2023-10-15T02:36:43.986212308Z",
|
||||
"end_time": null,
|
||||
"type": "modal",
|
||||
"message": "TG9yZW0gaXBzdW0gZG9sb3Igc2l0IGFtZXQsIGNvbnNlY3RldHVyIGFkaXBpc2NpbmcgZWxpdC4gQ3VyYWJpdHVyIG51bGxhIGF1Z3VlLCBwbGFjZXJhdCBxdWlzIHJpc3VzIGJsYW5kaXQsIG1vbGVzdGllIGltcGVyZGlldCBtYXNzYS4gU2VkIGJsYW5kaXQgcnV0cnVtIG9kaW8gcXVpcyB2YXJpdXMuIEZ1c2NlIHB1cnVzIG9yY2ksIG1heGltdXMgYWMgbGliZXJvLgo",
|
||||
"authenticated": false,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete custom message
|
||||
|
||||
This endpoint deletes a specific custom message.
|
||||
|
||||
| Method | |
|
||||
| :------- | :----------------------------------- |
|
||||
| `DELETE` | `/sys/config/ui/custom-messages/:id` |
|
||||
|
||||
### Parameters
|
||||
|
||||
- `id` `(string: <required>)` - The unique ID assigned to the custom message at creation time.
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl --header "X-Vault-Token: ..." \
|
||||
http://127.0.0.1:8200/v1/sys/config/ui/custom-messages/01234567-89ab-cdef-0123-456789abcdef
|
||||
```
|
||||
@@ -1,19 +1,19 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/config/ui - HTTP API
|
||||
description: The '/sys/config/ui' endpoint configures the UI.
|
||||
page_title: /sys/config/ui/headers - HTTP API
|
||||
description: The '/sys/config/ui/headers' endpoint configures the UI.
|
||||
---
|
||||
|
||||
# `/sys/config/ui`
|
||||
# `/sys/config/ui/headers`
|
||||
|
||||
@include 'alerts/restricted-root.mdx'
|
||||
|
||||
The `/sys/config/ui` endpoint is used to configure UI settings.
|
||||
The `/sys/config/ui/headers` endpoint is used to configure UI header settings.
|
||||
|
||||
- **`sudo` required** – All UI endpoints require `sudo` capability in
|
||||
- **`sudo` required** – All of these endpoints require the `sudo` capability in
|
||||
addition to any path-specific capabilities.
|
||||
|
||||
## Read UI settings
|
||||
## Read UI header settings
|
||||
|
||||
This endpoint returns the given UI header configuration.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/internal/ui/authenticated-messages - HTTP API
|
||||
description: >-
|
||||
The `/sys/internal/ui/authenticated-messages` endpoint retrieves active post-login custom messages.
|
||||
---
|
||||
|
||||
# `/sys/internal/ui/authenticated-messages`
|
||||
|
||||
The `/sys/internal/ui/authenticated-messages` endpoint is used by the UI to
|
||||
retrieve the active post-login custom messages so that it can display them.
|
||||
|
||||
When retrieving custom messages, the results will include active messages from
|
||||
the current namespace along with custom messages that exist all of the ancestral
|
||||
namespaces up to and including the root namespace.
|
||||
|
||||
This should only be used internally by the UI. Due to the nature of its
|
||||
intended usage, there is no guarantee on backwards compatibility for this endpoint.
|
||||
|
||||
## Get post-login custom messages
|
||||
|
||||
This endpoint lists the active post-login custom messages.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :------------------------------------------ |
|
||||
| `GET` | `/sys/internal/ui/authenticated-messages` |
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
http://127.0.0.1:8200/v1/sys/internal/ui/authenticated-messages
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"key_info": {
|
||||
"01234567-89ab-cdef-0123-456789abcdef": {
|
||||
"title": "Post-login Advisory",
|
||||
"message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur nulla augue, placerat quis risus blandit, molestie imperdiet massa. Sed blandit rutrum odio quis varius. Fusce purus orci, maximus ac libero.",
|
||||
"type": "modal",
|
||||
"authenticated": true,
|
||||
"start_time": "2024-01-01T00:00:00.000000000Z",
|
||||
"end_time": null,
|
||||
"options": null,
|
||||
"link": {
|
||||
"Details": "https://www.example.org/details"
|
||||
}
|
||||
}
|
||||
},
|
||||
"keys": [
|
||||
"01234567-89ab-cdef-0123-456789abcdef"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
layout: api
|
||||
page_title: /sys/internal/ui/unauthenticated-messages - HTTP API
|
||||
description: >-
|
||||
The `/sys/internal/ui/unauthenticated-messages` endpoint retrieves active pre-login custom messages.
|
||||
---
|
||||
|
||||
# `/sys/internal/ui/unauthenticated-messages`
|
||||
|
||||
The `/sys/internal/ui/unauthenticated-messages` endpoint is used by the UI to
|
||||
retrieve the active pre-login custom messages so that it can display them.
|
||||
|
||||
When retrieving custom messages, the results will include active messages from
|
||||
the current namespace along with custom messages that exist all of the ancestral
|
||||
namespaces up to and including the root namespace.
|
||||
This should only be used internally by the UI. Due to the nature of its
|
||||
intended usage, there is no guarantee on backwards compatibility for this endpoint.
|
||||
|
||||
## Get pre-login custom messages
|
||||
|
||||
This endpoint lists the active pre-login custom messages.
|
||||
|
||||
| Method | Path |
|
||||
| :----- | :------------------------------------------ |
|
||||
| `GET` | `/sys/internal/ui/unauthenticated-messages` |
|
||||
|
||||
### Sample request
|
||||
|
||||
```shell-session
|
||||
$ curl \
|
||||
http://127.0.0.1:8200/v1/sys/internal/ui/unauthenticated-messages
|
||||
```
|
||||
|
||||
### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"key_info": {
|
||||
"01234567-89ab-cdef-0123-456789abcdef": {
|
||||
"title": "Pre-login Warning",
|
||||
"message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur nulla augue, placerat quis risus blandit, molestie imperdiet massa. Sed blandit rutrum odio quis varius. Fusce purus orci, maximus ac libero.",
|
||||
"type": "modal",
|
||||
"authenticated": false,
|
||||
"start_time": "2024-01-01T00:00:00.000000000Z",
|
||||
"end_time": null,
|
||||
"options": null,
|
||||
"link": {
|
||||
"Details": "https://www.example.org/details"
|
||||
}
|
||||
}
|
||||
},
|
||||
"keys": [
|
||||
"01234567-89ab-cdef-0123-456789abcdef"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -439,8 +439,12 @@
|
||||
"path": "system/config-state"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/config/ui</code>",
|
||||
"path": "system/config-ui"
|
||||
"title": "<code>/sys/config/ui/custom-messages</code>",
|
||||
"path": "system/config-ui-custom-messages"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/config/ui/headers</code>",
|
||||
"path": "system/config-ui-headers"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/control-group</code>",
|
||||
@@ -499,6 +503,10 @@
|
||||
"title": "<code>/sys/internal/specs/openapi</code>",
|
||||
"path": "system/internal-specs-openapi"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/internal/ui/authenticated-messages</code>",
|
||||
"path": "system/internal-ui-authenticated-messages"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/internal/ui/feature-flags</code>",
|
||||
"path": "system/internal-ui-feature"
|
||||
@@ -515,6 +523,10 @@
|
||||
"title": "<code>/sys/internal/ui/resultant-acl</code>",
|
||||
"path": "system/internal-ui-resultant-acl"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/internal/ui/unauthenticated-messages</code>",
|
||||
"path": "system/internal-ui-unauthenticated-messages"
|
||||
},
|
||||
{
|
||||
"title": "<code>/sys/internal/ui/version</code>",
|
||||
"path": "system/internal-ui-version"
|
||||
|
||||
Reference in New Issue
Block a user