/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: <optional>) - 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: <optional>) - The list of GCP location names for which the destination may replicate secret data into. Regardless of the selected regions for storing the secrets, they will remain globally readable when configured as such.
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: <optional>) - Fine-grained or personal access token. Use access_token as an alternative to authenticating with a GitHub app.
app_name (string: <optional>) - 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: <optional>) - The installation ID of the GitHub app to use for authentication. Required when using app_name for authentication.
repository_owner (string: <optional>) - GitHub username or organization name that owns the single repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the owner is hashicorp. Requires secrets_location to be repository.
- repository_name (string: <optional>) - Name of the repository. For example, if a repository is located at https://github.com/hashicorp/vault.git the name is vault. Requires secrets_location to be repository.
- environment_name (string: "") - Name of a GitHub environment within the repo specified by repository_name. By default, secrets are global to the targeted repository. Requires secrets_location to be repository.
organization_name (string: <optional>) - (BETA) Name of the GitHub organization. For example, if your organization is located at https://github.com/hashicorp the name is hashicorp. Requires secrets_location to be organization.
- organization_visibility (string: <optional>) - (BETA) Controls which repositories within the organization will be able to see the synced secrets. Must be one of all, private, or selected. When set to all, all repositories have access to the secret. When set to private, only private and internal repositories have access. When set to selected, only the repositories listed in the selected_repository_names field have access. Requires secrets_location to be organization.
- selected_repository_names (list: <optional>) - (BETA) The list of repository names within the organization that will be able to see the synced secrets. Requires secrets_location to be 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.

Sample repository environment payload

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

Sample organization payload

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