/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 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.
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.
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
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
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.
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 parameter
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: <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.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.
Sample payload
Sample request
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' and 'production'.
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