mirrors/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2025-08-22 23:21:08 +02:00
Code Issues Projects Releases Wiki Activity
vault/website/content/api-docs/system/secrets-sync.mdx
Robert 9573218254
Fix small typo/anchor link in GCP sync API docs section (#29821) 
* Fix typo

* Update secrets-sync.mdx
2025-03-04 13:05:42 -06:00

1074 lines
32 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: /sys/sync - HTTP API
description: The `/sys/sync` endpoints are used to configure destinations and associate secrets to sync with these destinations.
---
# `/sys/sync`
@include 'alerts/enterprise-only.mdx'
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.
@include 'alerts/restricted-admin.mdx'
| 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
```json
{
"disabled": "true",
"queue_capacity": 1000000
}
```
### Sample request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request PATCH \
--data @payload.json
http://127.0.0.1:8200/v1/sys/sync/config
```
### Sample response
```json
{
"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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/sync/destinations
```
### Sample response
```json
{
"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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm
```
### Sample response
```json
{
"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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/destinations/aws-sm/my-store-1
```
### Sample response
```json
{
"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
```shell-session
$ 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](/vault/docs/sync#name-template) 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](/vault/docs/sync#granularity) for more details.
@include 'sync-ssrf-fields.mdx'
### Sample payload
```json
{
"access_key_id": "AKI***",
"secret_access_key": "ktri****",
"region": "us-west-1",
"allowed_ipv4_addresses": [
"10.0.100.1/24",
"10.0.200.1/16"
]
}
```
### Sample request
```shell-session
$ 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
```json
{
"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](/vault/docs/sync#name-template) 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](/vault/docs/sync#granularity) for more details.
@include 'sync-ssrf-fields.mdx'
### Sample payload
```json
{
"key_vault_uri": "https://keyvault-1234abcd.vault.azure.net",
"tenant_id": "uuid",
"client_id": "uuid",
"client_secret": "90y8Q***",
"allowed_ipv6_addresses": [
"fe80::0/120",
"fe80::100/120"
]
}
```
### Sample request
```shell-session
$ 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](/vault/docs/secrets/gcp#authentication) 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](https://cloud.google.com/iam/docs/service-account-overview#locations)
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.
- `locational_kms_keys` `(map<string|string>: nil)` - A map of location names to KMS key names to leverage customer-managed encryption keys for
encryption at rest. Each pair follows the format `location_name=encryption_key_resource_ID`. Refer to the
[sample payloads](#sample-payloads) for more details.
- `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](/vault/docs/sync#name-template) 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](/vault/docs/sync#granularity) for more details.
@include 'sync-ssrf-fields.mdx'
### Sample payloads
#### Sync secrets to GCP without SSRF-safe networking:
```json
{
"credentials": "<private key string>",
"replication_locations": [
"us-east1",
"us-west1"
],
"disable_strict_networking": true
}
```
#### Sync secrets to GCP with a global KMS key:
```json
{
"credentials": "<private key string>",
"global_kms_key": "projects/my-project/locations/global/keyRings/my-global-keyring/cryptoKeys/my-global-key"
}
```
#### Sync secrets to GCP with locational KMS keys:
```json
{
"credentials": "<private key string>",
"replication_locations": [
"us-east1",
"us-west1"
],
"locational_kms_keys": {
"us-east1": "projects/my-project/locations/us-east1/keyRings/my-east-keyring/cryptoKeys/my-east-key",
"us-west1": "projects/my-project/locations/us-west1/keyRings/my-west-keyring/cryptoKeys/my-west-key"
}
}
```
### Sample request
```shell-session
$ 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](/vault/api-docs/system/secrets-sync#configure-a-custom-github-app)
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](/vault/docs/sync#name-template) for more details.
- `granularity` `(string: "secret-key")` - Determines what level of information is synced as a distinct resource at the
destination. See [this documentation](/vault/docs/sync#granularity) for more details.
@include 'sync-ssrf-fields.mdx'
### Sample payloads
#### Sync secrets to a GitHub repository
```json
{
"access_token": "github_pat_12345",
"secrets_location": "repository",
"repository_owner": "my-organization-or-username",
"repository_name": "my-repository",
}
```
#### Sync secrets to a GitHub environment
```json
{
"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
```json
{
"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
```shell-session
$ 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](/vault/docs/sync#name-template) for more details.
- `granularity` `(string: "secret-key")` - Determines what level of information is synced as a distinct resource at the
destination. See [this documentation](/vault/docs/sync#granularity) for more details.
@include 'sync-ssrf-fields.mdx'
### Sample payload
```json
{
"access_token": "<token>>",
"project_id": "prj_12345",
"deployment_environments": ["development", "preview", "production"]
}
```
### Sample request
```shell-session
$ 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.
</Note>
| 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
```shell-session
$ 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
```json
{
"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.
</Note>
| 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
```json
{
"mount": "my-kv",
"secret_name": "my-secret-1"
}
```
### Sample request
```shell-session
$ 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
```json
{
"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
```json
{
"mount": "my-kv",
"secret_name": "my-secret-1"
}
```
### Sample request
```shell-session
$ 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
```json
{
"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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/sys/sync/associations
```
### Sample response
```json
{
"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 (`/`).
</Note>
| 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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/associations/my-kv-1/my-secret-1
```
```shell-session
$ 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
```json
{
"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
```json
{
"app_id": "true",
"private_key": "<PRIVATE KEY PEM>"
}
```
### Sample requests
```shell-session
$ 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
```json
{
"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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app
```
### Sample response
```json
{
"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
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/sys/sync/github-apps/my-custom-app
```
Reference in New Issue View Git Blame Copy Permalink