# /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.
* `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.
* `sha256` `(string: <required>)` – This is the SHA256 sum of the plugin's binary or the OCI image. Before a plugin is run, its SHA will be checked against this value. If they do not match the plugin can not be run.
* `command` `(string: <required>)` - 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.
* `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"`.

#### Sample payload

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/api/system-backend/sys-plugins-catalog.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.