---
layout: api
page_title: /sys/plugins/catalog - HTTP API
description: The `/sys/plugins/catalog` endpoint is used to manage plugins.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# `/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

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

### Sample response

```json
{
    "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

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

### Sample response

```json
{
    "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](https://releases.hashicorp.com/)

- `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](/vault/api-docs/system/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)` - <EnterpriseAlert inline="true" /> **( BETA )**
  Tells Vault to download the specified plugin from the
  [HashiCorp releases page](https://releases.hashicorp.com/). 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

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

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

#### Enterprise plugins

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

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

### Sample payload using OCI image

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

### Sample request

```shell-session
$ 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

```shell-session
$ 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

```json
{
  "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

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