diff --git a/website/content/api-docs/system/secrets-sync.mdx b/website/content/api-docs/system/secrets-sync.mdx index 72f9d9cb64..b258a8082c 100644 --- a/website/content/api-docs/system/secrets-sync.mdx +++ b/website/content/api-docs/system/secrets-sync.mdx @@ -38,17 +38,59 @@ $ curl \ "lease_duration": 0, "data": { "key_info": { - "aws-sm": [ + "aws-sm/": [ "my-dest-1" ], - "gh": [ + "gh/": [ "my-dest-1" ] }, "keys": [ - "aws-sm", - "gh" - ] + "aws-sm/", + "gh/" + ], + "total_destinations": 2 + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## List destinations by type + +This endpoint lists all configured sync destination names for a given type. + +| Method | Path | +|:-------|:-------------------------------| +| `LIST` | `/sys/sync/destinations/:type` | + +### Parameters + +- `type` `(string: )` - Specifies the destination type. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm +``` + +### Sample response + +```json +{ + "request_id": "uuid", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "keys": [ + "my-dest-1" + ], + "total_destinations": 1 }, "wrap_info": null, "warnings": null, @@ -341,8 +383,7 @@ $ curl \ http://127.0.0.1:8200/v1/sys/sync/destinations/vercel-project/my-store-1 ``` - -## Read Associations +## Read associations This endpoint returns all existing associations for a given destination. An association references the mount via its accessor. Associations also contain the latest sync status for the secret they represent. @@ -399,7 +440,7 @@ $ curl \ } ``` -## Set Association +## Set association The set endpoint links a secret to an existing destination using the secret name and mount path and triggers a sync operation. If the secret is already @@ -474,7 +515,7 @@ $ curl \ } ``` -## Remove Association +## Remove association The remove endpoint unlinks a secret from an existing destination based on the secret name and mount path, and triggers an unsync operation. Unsync @@ -541,3 +582,130 @@ $ curl \ "auth": null } ``` + +## List associations + +This endpoint lists all secrets referenced by at least one association. Each secret can be associated with multiple +destinations, so the total number of associations can be greater than the total number of synced secrets. + +| Method | Path | +|:-------|:-------------------------| +| `LIST` | `/sys/sync/associations` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/sys/sync/associations +``` + +### Sample response + +```json +{ + "request_id": "uuid", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "key_info": { + "my-kv-1/my-secret-1": [ + { + "mount": "my-kv-1/", + "secret_path": "my-secret-1" + } + ], + "my/kv/1/my/secret/1": [ + { + "mount": "my/kv/1/", + "secret_path": "my/secret/1" + } + ] + }, + "keys": [ + "my/kv/1/my/secret/1", + "my-kv-1/my-secret-1" + ], + "total_associations": 4, + "total_secrets": 2 + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Read destinations by secret + +This endpoint returns all destinations associated with the provided secret reference. + + + + The request is available either with path parameters or request parameters to support + mounts or secrets with forward slash characters (`/`). + + + +| Method | Path | +|:-------|:--------------------------------------| +| `GET` | `/sys/sync/associations/:mount/:name` | + +| Method | Path | +|:-------|:---------------------------------------------------------------------| +| `GET` | `/sys/sync/associations/destinations?mount=:mount&secret_name=:name` | + +### Parameters + +- `mount` `(string: )` - Specifies the mount where the secret is located. For example, if you can read a secret +with `vault kv get -mount=my-kv my-secret-1`, the mount name is `my-kv`. + +- `name` `(string: )` - Specifies the name of the synchronized secret. For example, if you can read a secret +with `vault kv get -mount=my-kv my-secret-1`, the secret name is `my-secret-1`. + +### Sample requests + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/sys/sync/associations/my-kv-1/my-secret-1 +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/sys/sync/associations/destinations?mount=my-kv-1&secret_name=my-secret-1 +``` + +### Sample response + +```json +{ + "request_id": "uuid", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "associated_destinations": { + "aws-sm/my-dest-1": { + "type": "aws-sm", + "name": "my-dest-1", + "sync_status": "UNSYNCED", + "updated_at": "2023-11-02T14:24:24.07391144-04:00" + }, + "gh/my-dest-1": { + "type": "gh", + "name": "my-dest-1", + "sync_status": "SYNCED", + "updated_at": "2023-11-02T14:24:28.719833506-04:00" + } + } + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +```