mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-18 21:21:06 +02:00
Code Issues Projects Releases Wiki Activity
vault/website/content/api-docs/system/secrets-sync.mdx
Max Coulombe 7106e6c22f
* fix remove endpoint doc (#23329)
2023-09-27 15:40:07 -04:00

539 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: ..." \
--reuquest 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.
- `repisitory_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 synchronisation 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
--data @payload.json
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
This endpoint sets a new association for a given destination. If an equivalent association already exists, this request
does not create a duplicate but will trigger a sync operation and refresh the secret value on the external system.
<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
This endpoint removes an existing association for a given destination. If an equivalent association already exists, this request
does not create a duplicate but will trigger a sync operation and refresh the secret value on 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