/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