mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-15 19:17:02 +02:00
Code Issues Projects Releases Wiki Activity
2b51e09bda
vault/website/content/api-docs/system/secrets-sync.mdx
claire bontempo db4819427a
docs/add line separators to curl requests secrets sync (#23681) 
* add line separators to curl requests

* revert unsync change
2023-10-23 08:29:26 -07:00

545 lines
15 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: /sys/sync - HTTP API
description: The `/sys/sync` endpoints are used to configure destinations and associate secrets to sync with these destinations.
---
# `/sys/sync`
The `/sys/sync` endpoints are used to configure destinations and associate secrets to sync with these destinations.
Each destination type has its own endpoint for creation & update operations, but share the same endpoints for read &
delete operations.
## List destinations
This endpoint lists all configured sync destination names regrouped by destination type.
| Method | Path |
|:-------|:-------------------------|
| `LIST` | `/sys/sync/destinations` |
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/sync/destinations
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"key_info": {
"aws-sm": [
"my-dest-1"
],
"gh": [
"my-dest-1"
]
},
"keys": [
"aws-sm",
"gh"
]
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Read destination
This endpoint retrieves information about the destination of a given type and name. Sensitive information from the
connection details are obfuscated.
| Method | Path |
|:-------|:-------------------------------------|
| `GET` | `/sys/sync/destinations/:type/:name` |
### Parameters
- `type` `(string: <required>)` - Specifies the destination type. This is specified as part of the URL.
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"connection_details": {
"access_key_id": "*****",
"secret_access_key": "*****",
"region": "us-west-1"
},
"name": "my-store-1",
"type": "aws-sm"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Delete destination
This endpoint deletes information about the destination of a given type and name if it exists. Destinations still managing
associations cannot be deleted.
| Method | Path |
|:---------|:-------------------------------------|
| `DELETE` | `/sys/sync/destinations/:type/:name` |
### Parameters
- `type` `(string: <required>)` - Specifies the destination type. This is specified as part of the URL.
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1
```
## Create/Update AWS Secrets Manager destination
This endpoint creates a destination to synchronize secrets with the AWS Secrets manager.
| Method | Path |
|:-------|:--------------------------------------|
| `POST` | `/sys/sync/destinations/aws-sm/:name` |
### Parameters
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `access_key_id` `(string: "")` - Access key id to authenticate against the AWS secrets manager. If omitted, authentication
fallbacks on the AWS credentials provider chain and tries to infer authentication from the environment.
- `secret_access_key` `(string: "")` - Secret access key to authenticate against the AWS secrets manager. If omitted,
authentication fallbacks on the AWS credentials provider chain and tries to infer authentication from the environment.
- `region` `(string: "")` - Region where to manage the secrets manager entries. If omitted, configuration fallbacks on
the AWS credentials provider chain and tries to infer region from the environment.
### Sample payload
```json
{
"access_key_id": "AKI***",
"secret_access_key": "ktri****",
"region": "us-west-1"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"connection_details": {
"access_key_id": "*****",
"secret_access_key": "*****",
"region": "us-west-1"
},
"name": "my-store-1",
"type": "aws-sm"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## Create/Update Azure Key Vault destination
This endpoint creates a destination to synchronize secrets with an Azure Key Vault instance.
| Method | Path |
|:-------|:----------------------------------------|
| `POST` | `/sys/sync/destinations/azure-kv/:name` |
### Parameters
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `key_vault_uri` `(string: <required>)` - URI of an existing Azure Key Vault instance.
- `client_id` `(string: <required>)` - Client ID of an Azure app registration.
- `client_secret` `(string: <required>)` - Client secret of an Azure app registration.
- `tenant_id` `(string: <required>)` - ID of the target Azure tenant.
- `cloud` `(string: "cloud")` - Specifies a cloud for the client. The default is Azure Public Cloud.
### Sample payload
```json
{
"key_vault_uri": "https://keyvault-1234abcd.vault.azure.net",
"subscription_id": "uuid",
"tenant_id": "uuid",
"client_id": "uuid",
"client_secret": "90y8Q***"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1
```
## Create/Update GCP Secret Manager destination
This endpoint creates a destination to synchronize secrets with the GCP Secret Manager.
| Method | Path |
|:-------|:--------------------------------------|
| `POST` | `/sys/sync/destinations/gcp-sm/:name` |
### Parameters
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `credentials` `(string: <required>)` - JSON credentials (either file contents or '@path/to/file')
See docs for [alternative ways](/vault/docs/secrets/gcp#authentication) to pass in to this parameter
### Sample payload
```json
{
"credentials": "<JSON string>"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/sys/sync/destinations/gcp-sm/my-store-1
```
## Create/Update GitHub Repository Action destination
This endpoint creates a destination to synchronize action secrets with a GitHub repository.
| Method | Path |
|:-------|:----------------------------------|
| `POST` | `/sys/sync/destinations/gh/:name` |
### Parameters
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `access_token` `(string: <required>)` - Fine-grained or personal access token.
- `repository_owner` `(string: <required>)` - GitHub organization or username that owns the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the owner is hashicorp.
- `repository_name` `(string: <required>)` - Name of the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the name is vault.
### Sample payload
```json
{
"access_token": "github_pat_12345",
"repository_owner": "my-organization-or-username",
"repository_name": "my-repository"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/sys/sync/destinations/gh/my-store-1
```
## Create/Update Vercel Project destination
This endpoint creates a destination to synchronize secrets with the GCP Secret Manager.
| Method | Path |
|:-------|:----------------------------------------------|
| `POST` | `/sys/sync/destinations/vercel-project/:name` |
### Parameters
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `access_token` `(string: <required>)` - Vercel API access token with the permissions to manage environment variables.
- `project_id` `(string: <required>)` - Project ID where to manage environment variables.
- `team_id` `(string: "")` - Team ID the project belongs to. Optional.
- `deployment_environments` `(string: <required>)` - Deployment environments where the environment variables are available. Accepts 'development', 'preview' & 'production'.
### Sample payload
```json
{
"access_token": "<token>>",
"project_id": "prj_12345",
"deployment_environments": ["development", "preview", "production"]
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json
http://127.0.0.1:8200/v1/sys/sync/destinations/vercel-project/my-store-1
```
## 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.
<Note>
In the event a synchronization operation does not succeed, the sync status will indicate the cause
of the error and is a useful tool when troubleshooting.
</Note>
| Method | Path |
|:-------|:--------------------------------------------------|
| `GET` | `/sys/sync/destinations/:type/:name/associations` |
### Parameters
- `type` `(string: <required>)` - Specifies the destination type. This is specified as part of the URL.
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1/associations
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"associated_secrets": {
"kv_eb4acbae/my-secret-1": {
"accessor": "kv_eb4acbae",
"secret_name": "my-secret-1",
"sync_status": "SYNCED",
"updated_at": "2023-09-20T10:51:53.961861096-04:00"
}
},
"store_name": "my-store-1",
"store_type": "aws-sm"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## 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
associated with the destination, Vault performs a refresh without recreating the
link. Triggering a refresh is useful to push the secret to external systems
or retry a failed sync operation if the underlying problem that caused the
failure has been resolved.
<Note>
Only KV-v2 secrets are supported at the moment.
</Note>
| Method | Path |
|:-------|:------------------------------------------------------|
| `POST` | `/sys/sync/destinations/:type/:name/associations/set` |
### Parameters
- `type` `(string: <required>)` - Specifies the destination type. This is specified as part of the URL.
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `mount` `(string: <required>)` - 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`.
- `secret_name` `(string: <required>)` - Specifies the name of the secret to synchronize. 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 payload
```json
{
"mount": "my-kv",
"secret_name": "my-secret-1"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1/associations/set
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"associated_secrets": {
"kv_eb4acbae/my-secret-1": {
"accessor": "kv_eb4acbae",
"secret_name": "my-secret-1",
"sync_status": "SYNCED",
"updated_at": "2023-09-20T10:51:53.961861096-04:00"
}
},
"store_name": "my-store-1",
"store_type": "aws-sm"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
## 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
operations delete the secret from the external system. The unsync operation
reports success if the targeted association is removed, does not exist, or the
secret was already removed from the external system.
| Method | Path |
|:-------|:---------------------------------------------------------|
| `POST` | `/sys/sync/destinations/:type/:name/associations/remove` |
### Parameters
- `type` `(string: <required>)` - Specifies the destination type. This is specified as part of the URL.
- `name` `(string: <required>)` - Specifies the name for this destination. This is specified as part of the URL.
- `mount` `(string: <required>)` - 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: <required>)` - Specifies the name of the secret to synchronize. 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 payload
```json
{
"mount": "my-kv",
"secret_name": "my-secret-1"
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1/associations/remove
```
### Sample response
```json
{
"request_id": "uuid",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"associated_secrets": {
"kv_eb4acbae/my-secret-1": {
"accessor": "kv_eb4acbae",
"secret_name": "my-secret-1",
"sync_status": "UNSYNCED",
"updated_at": "2023-09-20T10:51:53.961861096-04:00"
}
},
"store_name": "my-store-1",
"store_type": "aws-sm"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
Reference in New Issue View Git Blame Copy Permalink