/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