/sys/plugins/catalog

The /sys/plugins/catalog endpoint is used to read, register, update, and remove plugins in Vault's catalog. Plugins must be registered before use, and once registered backends can use the plugin by querying the catalog.

LIST plugins

This endpoint lists the plugins in the catalog by type.

Method	Path
`GET`	`/sys/plugins/catalog`

Sample request

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

Sample response

{
    "data": {
        "auth": [
            "aws",
            "azure",
            "custom-auth-plugin",
            "gcp",
            "ldap"
        ],
        "database": [
            "cassandra-database-plugin",
            "mssql-database-plugin",
            "mysql-database-plugin",
            "postgresql-database-plugin"
        ],
        "detailed": [
            {
                "builtin": true,
                "deprecation_status": "supported",
                "name": "aws",
                "type": "auth",
                "version": "v1.12.0+builtin.vault"
            },
            ...
            {
                "builtin": true,
                "deprecation_status": "supported",
                "name": "cassandra-database-plugin",
                "type": "database",
                "version": "v1.12.0+builtin.vault"
            },
            ...
            {
                "builtin": true,
                "deprecation_status": "supported",
                "name": "aws",
                "type": "secret",
                "version": "v1.12.0+builtin.vault"
            },
            ...
            {
                "builtin": false,
                "name": "example-plugin",
                "type": "secret",
                "oci_image": "example-secret-plugin-oci-image",
                "runtime": "example-runtime",
                "version": "v1.0.0"
            },
            ...
        ],
        "secret": [
            "ad",
            "aws",
            "azure",
            "gcp",
            "transit",
            "example-plugin",
        ]
    }
}

LIST plugins

This endpoint lists the plugins in the catalog by type.

Method	Path
`LIST`	`/sys/plugins/catalog/auth`
`LIST`	`/sys/plugins/catalog/database`
`LIST`	`/sys/plugins/catalog/secret`

Sample request

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

Sample response

{
    "data": {
        "keys": [
            "aws",
            "azure",
            "custom-auth-plugin",
            "gcp",
            "ldap"
        ]
    }
}

Register plugin

This endpoint registers a new plugin, or updates an existing one with the supplied name.

sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

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

Parameters

name (string: <required>) – Specifies the name for this plugin. The name is what is used to look up plugins in the catalog. This is part of the request URL. Enterprise plugin names must match the name listed on the HashiCorp releases page
type (string: <required>) – Specifies the type of this plugin. May be "auth", "database", or "secret".
oci_image (string: "") - Specifies OCI image to run. If specified, setting command, args, and env will update the container's entrypoint, args, and environment variables (append-only) respectively.
runtime (string: "") - Specifies Vault plugin runtime to use if oci_image is specified. See /sys/plugins/runtimes/catalog for additional information.
version (string: "") - Specifies the semantic version of the plugin. Used as the tag when specifying oci_image, but with any leading 'v' trimmed. You can omit version to register a plugin binary, but you must provide an explicit version to register an extracted .zip file.
sha256 (string: "") – The SHA256 sum of a plugin binary or the OCI image. Before Vault runs a plugin, it checks the plugin SHA against sha256. If the actual SHA of the plugin binary and the SHA provided in sha256 do not match, Vault will not run the plugin. You must provide sha256 to register a plugin binary, but you must leave sha256 unset to register an extracted .zip file.
command (string: "") - Specifies the command used to execute the plugin. This is relative to the plugin directory. e.g. "myplugin", or if oci_image is also specified, it is relative to the image's working directory. You must provide command to register a plugin binary. Vault ignores command when you register with an extracted .zip file as it already knows the associated run command.
args (array: []) – Specifies the arguments used to execute the plugin. If the arguments are provided here, the command parameter should only contain the named program. e.g. "--my_flag=1".
env (array: []) – Specifies the environment variables used during the execution of the plugin. Each entry is of the form "key=value". e.g "FOO=BAR".
download (bool: false) - Enterprise ( BETA ) Tells Vault to download the specified plugin from the HashiCorp releases page. Automatic downloads only support secret and auth plugins with artifacts containing metadata.json and metadata.json.sig. To use automatic downloads, your network must permit HTTPS and TCP port 443 between all Vault cluster nodes and releases.hashicorp.com.

Sample payload

Community plugins

{
  "sha256": "d130b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961e9",
  "command": "mysql-database-plugin",
  "type": "database"
}

{
  "version": "0.24.0",
  "download": true
}

Enterprise plugins

{
  "version": "0.16.0+ent",
  "name": "vault-plugin-secrets-keymgmt",
  "type": "secret"
}

{
  "version": "0.16.0+ent",
  "download": true
}

Sample payload using OCI image

{
  "sha256": "d150b9a0fbfddef9709d8ff92e5e6053ccd246b78632fc03b8548457026961a9",
  "oci_image": "example-secret-plugin-oci-image",
  "runtime": "example-runtime"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin

Read plugin

This endpoint returns the configuration data for the plugin with the given name.

sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
`GET`	`/sys/plugins/catalog/:type/:name?version=:version`

Parameters

name (string: <required>) – Specifies the name of the plugin to retrieve. This is part of the request URL.
type (string: <required>) – Specifies the type of this plugin. May be "auth", "database", or "secret".
version (string: "") – The semantic version of the plugin to read. Required if the plugin was registered with a version.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin?version=v1.0.0

Sample response

{
  "data": {
    "args": [],
    "builtin": false,
    "runtime": "example-runtime",
    "oci_image": "example-secret-plugin-oci-image",
    "command": "/example-secret-plugin",
    "name": "example-plugin",
    "sha256": "0TC5oPv93vlwnY/5Ll5gU8zSRreGMvwDuFSEVwJpYek=",
    "version": "v1.0.0"
  }
}

Remove plugin from catalog

This endpoint removes the plugin with the given name.

sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
`DELETE`	`/sys/plugins/catalog/:type/:name?version=:version`

Parameters

name (string: <required>) – Specifies the name of the plugin to delete. This is part of the request URL.
type (string: <required>) – Specifies the type of this plugin. May be "auth", "database", or "secret".
version (string: "") – Specifies the semantic version of the plugin to delete.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/sys/plugins/catalog/secret/example-plugin?version=v1.0.0