/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 of PENDING until they are completed. This is provided as a safety mechanism for emergencies.

Sample payload

{
    "disabled": "true"
}

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

$ 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

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

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

Sample payload

{
    "credentials": "<JSON string>"
}

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

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

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

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