/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 ofPENDING
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
Sample request
Sample response
List destinations
This endpoint lists all configured sync destination names regrouped by destination type.
Method | Path |
---|---|
LIST | /sys/sync/destinations |
Sample request
Sample response
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
Sample response
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
Sample response
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
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 likevault/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
Sample request
Sample response
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 likevault-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
Sample request
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 parameterproject_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.secret_name_template
(string: "")
- Template to use when generating the secret names on the external system. The default template yields names likevault/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
Sample request
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: <optional>)
- Fine-grained or personal access token. Useaccess_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. Useapp_name
andinstallation_id
as an alternative to authenticating with an access token.installation_id
(string: <optional>)
- The installation ID of the GitHub app to use for authentication. Required when usingapp_name
for authentication.
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.secret_name_template
(string: "")
- Template to use when generating the secret names on the external system. The default template yields names likeVAULT_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
Sample request
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 likevault/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
Sample request
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
Sample response
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 withvault kv get -mount=my-kv my-secret-1
, the mount name ismy-kv
.secret_name
(string: <required>)
- Specifies the name of the secret to synchronize. For example, if you can read a secret withvault kv get -mount=my-kv my-secret-1
, the secret name ismy-secret-1
.
Sample payload
Sample request
Sample response
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 withvault kv get -mount=my-kv my-secret-1
, the mount name ismy-kv
.name
(string: <required>)
- Specifies the name of the secret to synchronize. For example, if you can read a secret withvault kv get -mount=my-kv my-secret-1
, the secret name ismy-secret-1
.
Sample payload
Sample request
Sample response
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
Sample response
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 withvault kv get -mount=my-kv my-secret-1
, the mount name ismy-kv
.name
(string: <required>)
- Specifies the name of the synchronized secret. For example, if you can read a secret withvault kv get -mount=my-kv my-secret-1
, the secret name ismy-secret-1
.
Sample requests
Sample response
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 that is used when configuring the destination. Although this can be any name, 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
Sample requests
Sample response
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
Sample response
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