/sys/plugins/pins

Use the /sys/plugins/pins endpoint to read, create, update, and delete pinned plugin versions in your Vault catalog.

When you pin a plugin version, Vault starts all instances of that name and type with the configured version, even if the mount was originally configured with a different version.

Note

You must register a plugin version before pinning it.
You must delete a pin before deleting the associated plugin version.
You must reload any plugins currently in use for the pinned version to take effect.

Create/update pinned version

Create a pinned version for a plugin with the given type and name.

Method	Path
`POST`	`/sys/plugins/pins/:type/:name`

Parameters

type (string: <required>) – Path parameter specifying the target plugin type for the pinned version. May be "auth", "database", or "secret".
name (string: <required>) – Path parameter specifying the plugin name for the pinned version.
version (string: <required>) - Specifies the semantic version of the plugin to pin. Cannot be a builtin version and must already exist in the catalog.

Sample payload

{  "version": "v1.0.0" }

Sample request

$ curl \  --header "X-Vault-Token: ..." \  --request POST \  --data @payload.json \  http://127.0.0.1:8200/v1/sys/plugins/pins/auth/github

List pinned versions

This endpoint lists all pinned versions.

Method	Path
`GET`	`/sys/plugins/pins`

Sample request

$ curl \  --header "X-Vault-Token: ..." \  http://127.0.0.1:8200/v1/sys/plugins/pins

Sample response

{  "data": {  "pinned_versions": [  {  "name": "github",  "type": "auth",  "version": "v1.0.0"  }  ]  } }

Read pinned version

Read the pinned version for a plugin with the given type and name.

Method	Path
`GET`	`/sys/plugins/pins/:type/:name`

Parameters

type (string: <required>) – Path parameter specifying the target plugin type for the pinned version. May be "auth", "database", or "secret".
name (string: <required>) – Path parameter specifying the plugin name for the pinned version.

Sample request

$ curl \  --header "X-Vault-Token: ..." \  --request GET \  http://127.0.0.1:8200/v1/sys/plugins/pins/auth/github

Sample response

{  "data": {  "name": "github",  "type": "auth",  "version": "v1.0.0"  } }

Delete pinned version

Delete any pinned version for a plugin with the given type and name.

Method	Path
`DELETE`	`/sys/plugins/pins/:type/:name

Parameters

type (string: <required>) – Path parameter specifying the target plugin type for the pinned version. May be "auth", "database", or "secret".
name (string: <required>) – Path parameter specifying the plugin name for the pinned version.

Sample request

$ curl \  --header "X-Vault-Token: ..." \  --request DELETE \  http://127.0.0.1:8200/v1/sys/plugins/pins/auth/github