/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.

Configuration

The sys/sync/config endpoint is used to set configuration parameters for the sync system as a whole.

Restricted endpoint

The API path can only be called from the root or administrative namespace.

Method	Path
`PATCH`	`sys/sync/config`

Parameters

disabled (bool: false) - Disables sync operations from sending secrets in Vault to external destinations when set to true. While disabled, actions performed in Vault which trigger a sync operation will instead get queued to be processed once syncing is reactivated. Queued operations will have a status of PENDING until they are completed. This is provided as a safety mechanism for emergencies.
queue_capacity (int: 1,000,000) - Maximum number of pending sync operations allowed on the internal queue.

Sample payload

{
    "disabled": "true",
    "queue_capacity": 1000000
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request PATCH \
    --data @payload.json
    http://127.0.0.1:8200/v1/sys/sync/config

Sample response

{
    "request_id": "uuid",
    "lease_id": "",
    "lease_duration": 0,
    "renewable": false,
    "data": {
        "disabled": true,
        "queue_capacity": 1000000
    },
    "warnings": null,
    "mount_type": "system"
}

List destinations

This endpoint lists all configured sync destination names regrouped by destination type.

Method	Path
`LIST`	`/sys/sync/destinations`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/sync/destinations

Sample response

{
    "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/"
        ],
        "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: <required>) - Specifies the destination type. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm

Sample response

{
    "request_id": "uuid",
    "lease_id": "",
    "renewable": false,
    "lease_duration": 0,
    "data": {
        "keys": [
            "my-dest-1"
        ],
        "total_destinations": 1
    },
    "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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1

Sample response

{
    "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",
        "options": {
            "granularity_level": "secret-path",
            "secret_name_template": "vault/{{ .MountAccessor }}/{{ .SecretPath }}"
        },
        "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 unless they are also purged.

Method	Path
`DELETE`	`/sys/sync/destinations/:type/:name?purge=:purge`

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.
purge (bool: false) - If true, asynchronously unsync all secrets and delete all associations managed by this destination before it is deleted.

Sample request

$ 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.
role_arn (string: "") - Specifies a role to assume when connecting to AWS. When assuming a role, Vault uses temporary STS credentials to authenticate. An initial session with the proper trust relationship must exist for Vault to be able to assume this role. The role can be in a different account.
external_id (string: "") - Optional extra protection that must match the trust policy granting access to the AWS IAM role ARN. We recommend using a different random UUID per destination.
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.
secret_name_template (string: "") - Template to use when generating the secret names on the external system. The default template yields names like vault/kv_1234/my-secret. See this documentation for more details.
custom_tags (map<string|string>: nil) - List of custom tags or labels to set on the synced secrets at the destination. Custom tags are merged with internal built-in tags.
granularity (string: "secret-path") - Determines what level of information is synced as a distinct resource at the destination. See this documentation for more details.

Sample payload

{
    "access_key_id": "AKI***",
    "secret_access_key": "ktri****",
    "region": "us-west-1"
}

Sample request

$ 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

{
    "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",
        "options": {
            "custom_tags": {},
            "granularity_level": "secret-path",
            "secret_name_template": "vault/{{ .MountAccessor }}/{{ .SecretPath }}"
        },
        "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.
secret_name_template (string: "") - Template to use when generating the secret names on the external system. The default template yields names like vault-kv-1234-my-secret. See this documentation for more details.
custom_tags (map<string|string>: nil) - List of custom tags or labels to set on the synced secrets at the destination. Custom tags are merged with internal built-in tags.
granularity (string: "secret-path") - Determines what level of information is synced as a distinct resource at the destination. See this documentation for more details.

Sample payload

{
    "key_vault_uri": "https://keyvault-1234abcd.vault.azure.net",
    "tenant_id": "uuid",
    "client_id": "uuid",
    "client_secret": "90y8Q***"
}

Sample request

$ 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 to pass in to this parameter
project_id (string: "") - The target project to manage secrets in. If set, overrides the project ID derived from the service account JSON credentials or application default credentials. The service account must be authorized to perform Secret Manager actions in the target project.
replication_locations (list: nil) - A list of GCP location names the destination can use to store replicated secrets. Note that secrets remain globally readable regardless of the selected locations.
secret_name_template (string: "") - Template to use when generating the secret names on the external system. The default template yields names like vault/kv_1234/my-secret. See this documentation for more details.
custom_tags (map<string|string>: nil) - List of custom tags or labels to set on the synced secrets at the destination. Custom tags are merged with internal built-in tags.
granularity (string: "secret-path") - Determines what level of information is synced as a distinct resource at the destination. See this documentation for more details.

Sample payload

{
    "credentials": "<private key string>",
    "replication_locations": [
        "us-east1",
        "us-west1"
    ]
}

Sample request

$ 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.
secrets_location (string: "repository") - The GitHub location type of secrets to sync. Must be either organization or repository.
access_token (string: "" - Fine-grained or personal access token. Use access_token as an alternative to authenticating with a GitHub app.
app_name (string: "") - The name of a GitHub App configured in Vault to use for authentication. You can use app_name with installation_id as authentication instead of an access token. Refer to the Configure a custom GitHub app section of the Secrets sync API docs for more information.
- installation_id (string: "") - The installation ID of the GitHub app to use for authentication. Required when using app_name for authentication.
repository_owner (string: "") - GitHub owner of the secrets sync target location when secrets_location is repository. For example, if the target repository URL is https://github.com/hashicorp/vault.git, the owner is hashicorp.
- repository_name (string: "") - GitHub repository name of the secrets sync target location when secrets_location is repository. For example, if the target repository URL is https://github.com/hashicorp/vault.git, the repository name is vault.
- environment_name (string: "") - GitHub environment name of the secrets sync target location when secrets_location is repository. By default, secrets are global to the targeted repository.
organization_name (string: "") - (BETA) GitHub organization name of the secrets sync target location when secrets_location is organization. For example, if the organization is https://github.com/hashicorp, the organization name is hashicorp.
- organization_visibility (string: "") - (BETA) Controls which repositories within the secrets sync target location can see synced secrets when secrets_location is organization. Must be one of:
  - all - all repositories can access synced secrets
  - private - private and internal repositories can access synced secrets
  - selected - repositories explicitly named in selected_repository_names can access synced secrets.
- selected_repository_names (list: nil) - (BETA) Explicit list of repository names in the secrets sync target location that can access synced secrets when secrets_location is organization.
secret_name_template (string: "") - Template to use when generating the secret names on the external system. The default template yields names like VAULT_KV_1234_MY_SECRET. See this documentation for more details.
granularity (string: "secret-key") - Determines what level of information is synced as a distinct resource at the destination. See this documentation for more details.

Example requests

Sync secrets to a GitHub repository

{
    "access_token": "github_pat_12345",
    "secrets_location": "repository",
    "repository_owner": "my-organization-or-username",
    "repository_name": "my-repository",
}

Sync secrets to a GitHub environment

{
    "access_token": "github_pat_12345",
    "secrets_location": "repository",
    "repository_owner": "my-organization-or-username",
    "repository_name": "my-repository",
    "environment_name": "my-environment"
}

Sync secrets to a GitHub organization

{
    "access_token": "github_pat_12345",
    "secrets_location": "organization",
    "organization_name": "my-organization",
    "organization_visibility": "selected",
    "selected_repository_names": "my-repository-1,my-repository-2,my-repository-3"
}

Sample request

$ 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 a Vercel Project.

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' and 'production'.
secret_name_template (string: "") - Template to use when generating the secret names on the external system. The default template yields names like vault/kv_1234/my-secret. See this documentation for more details.
granularity (string: "secret-key") - Determines what level of information is synced as a distinct resource at the destination. See this documentation for more details.

Sample payload

{
    "access_token": "<token>>",
    "project_id": "prj_12345",
    "deployment_environments": ["development", "preview", "production"]
}

Sample request

$ 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.

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

$ 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

{
    "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.

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

{
    "mount": "my-kv",
    "secret_name": "my-secret-1"
}

Sample request

$ 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

{
    "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.
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

{
    "mount": "my-kv",
    "secret_name": "my-secret-1"
}

Sample request

$ 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

{
    "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
}

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

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/sys/sync/associations

Sample response

{
    "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.

Note

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: <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 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

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/sync/associations/my-kv-1/my-secret-1

$ 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

{
    "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
}

Configure a custom GitHub app

Use the POST operation with sys/sync/github-apps endpoint to configure a custom GitHub application for syncing secrets with GitHub repositories.

Method	Path
`POST`	`sys/sync/github-apps/:name`

Parameters

name (string: <required>) - Specifies a custom name for the GitHub application used when configuring a sync destination. We recommend using the same app name configured in GitHub.
app_id (string: <required>) - Specifies the GitHub application ID, provided by GitHub.
private_key (string: <required>) - Specifies the private key used to authenticate with the GitHub application.

Sample payload

{
    "app_id": "true",
    "private_key":  "<PRIVATE KEY PEM>"
}

Sample requests

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json
    http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app

Sample response

{
    "request_id": "uuid",
    "data": {
        "app_id": 123456,
        "fingerprint": "<fingerprint>",
        "name": "my-custom-app",
        "private_key": "*****"
    },
    "mount_type": "system"
}

Read custom GitHub app

Use the GET operation with sys/sync/github-apps to view details about the configured GitHub application.

Method	Path
`GET`	`sys/sync/github-apps/:name`

Parameters

name (string: <required>) - Specifies a custom name for the GitHub application.

Sample requests

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app

Sample response

{
    "request_id": "uuid",
    "data": {
        "app_id": 123456,
        "fingerprint": "<fingerprint>",
        "name": "my-custom-app",
        "private_key": "*****"
    },
    "mount_type": "system"
}

Delete custom GitHub app

Use the DELETE operation with sys/sync/github-apps to delete a configured GitHub application.

You cannot delete applications with active authentication destination references. Deleting an application configuration does not delete the GitHub application from GitHub.

Method	Path
`DELETE`	`sys/sync/github-apps/:name`

Parameters

name (string: <required>) - Specifies a custom name for the GitHub application.

Sample requests

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app