Merge 192c2aa into backport/patch-1/notably-grand-swine

website/content/api-docs/system/internal-ui-mounts.mdx

@@ -11,8 +11,11 @@ description: >-
 The `/sys/internal/ui/mounts` endpoint is used to manage mount listing
 visibility. The response generated by this endpoint is based on the
 `listing_visibility` value on the mount, which can be set during mount time or
-via mount tuning. This is currently only being used internally for the UI and is
-an unauthenticated endpoint.
+via mount tuning. This is currently only being used internally, for the UI and
+for CLI preflight checks, and is an unauthenticated endpoint.
+
+If called with a valid token in `X-Vault-Token` header, the response will
+include additional mounts which the token has been granted path capabilities on.
 
 Due to the nature of its intended usage, there is no guarantee on backwards
 compatibility for this endpoint.
@@ -45,8 +48,66 @@ $ curl \
   "secret": {
     "custom-secrets/": {
       "description": "Custom secrets",
+      "options": {
+        "version": "2"
+      },
       "type": "kv"
     }
   }
 }
 ```
+
+## Get Single Mount Details
+
+This endpoint lists details for a specific mount path. This is an
+authenticated endpoint, and is currently only being used internally.
+
+The calling token should not be granted permissions to these API endpoints
+directly, but instead rely on permissions granted to the individual mount path.
+This means that if you give a token a policy with capabilities on a `:path`
+(e.g. `/secret/*`), the token will be able to call
+`sys/internal/ui/mounts/:path` (e.g. `sys/internal/ui/mounts/secret`) without
+having to add that literal path to the policy document.
+
+On certain mounts, it is possible to call an arbitrary path within the engine
+(for example, `/sys/internal/ui/mounts/secret/path/to/secret` when the mount
+path is `/secret`). If called in this manner, then this endpoint will return the
+data for the mount that hosts that path. Therefore, a call to
+`/sys/internal/ui/mounts/secret/path/to/secret` and a call to
+`/sys/internal/ui/mounts/secret` will yield an identical response.
+
+Due to the nature of its intended usage, there is no guarantee on backwards
+compatibility for this endpoint.
+
+| Method | Path                            |
+| :----- | :------------------------------ |
+| `GET`  | `/sys/internal/ui/mounts/:path` |
+
+### Sample Request
+
+```shell-session
+$ curl \
+    --header "X-Vault-Token: ..." \
+    http://127.0.0.1:8200/v1/sys/internal/ui/mounts/cubbyhole
+```
+
+### Sample Response
+
+```json
+{
+  "accessor": "cubbyhole_50fbe8d2",
+  "config": {
+    "default_lease_ttl": 0,
+    "force_no_cache": false,
+    "max_lease_ttl": 0
+  },
+  "description": "per-token private secret storage",
+  "external_entropy_access": false,
+  "local": true,
+  "options": null,
+  "path": "cubbyhole/",
+  "seal_wrap": false,
+  "type": "cubbyhole",
+  "uuid": "4bb40403-d9ba-d2ee-087a-4c6d371db5f2"
+}
+```