---
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
}
```