open-vault/website/content/api-docs/secret/rabbitmq.mdx

---
layout: api
page_title: RabbitMQ - Secrets Engines - HTTP API
description: This is the API documentation for the Vault RabbitMQ secrets engine.
---

# RabbitMQ Secrets Engine (API)

This is the API documentation for the Vault RabbitMQ secrets engine. For general
information about the usage and operation of the RabbitMQ secrets engine, please
see the [RabbitMQ documentation](/docs/secrets/rabbitmq).

This documentation assumes the RabbitMQ secrets engine is enabled at the
`/rabbitmq` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.

## Configure Connection

This endpoint configures the connection string used to communicate with
RabbitMQ.

| Method | Path                          |
| :----- | :---------------------------- |
| `POST` | `/rabbitmq/config/connection` |

### Parameters

- `connection_uri` `(string: <required>)` – Specifies the RabbitMQ connection URI.

- `username` `(string: <required>)` – Specifies the RabbitMQ management administrator username.

- `password` `(string: <required>)` – Specifies the RabbitMQ management administrator password.

- `verify_connection` `(bool: true)` – Specifies whether to verify connection URI, username, and password.

- `password_policy` `(string: "")` - Specifies a [password policy](/docs/concepts/password-policies) to
  use when creating dynamic credentials. Defaults to generating an alphanumeric password if not set.

- `username_template` `(string)` - [Template](/docs/concepts/username-templating) describing how
  dynamic usernames are generated.

### Sample Payload

```json
{
  "connection_uri": "https://...",
  "username": "user",
  "password": "password",
  "password_policy": "rabbitmq_policy"
}
```

### Sample Request

<Tabs>
<Tab heading="cURL">

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/rabbitmq/config/connection
```

</Tab>
<Tab heading="CLI">

```shell-session
$ vault write rabbitmq/config/connection \
    connection_uri="http://localhost:8080" \
    username="user" \
    password="password" \
    password_policy="rabbitmq_policy"
```

</Tab>
</Tabs>

## Configure Lease

This endpoint configures the lease settings for generated credentials.

| Method | Path                     |
| :----- | :----------------------- |
| `POST` | `/rabbitmq/config/lease` |

### Parameters

- `ttl` `(int: 0)` – Specifies the lease ttl provided in seconds.

- `max_ttl` `(int: 0)` – Specifies the maximum ttl provided in seconds.

### Sample Payload

```json
{
  "ttl": 1800,
  "max_ttl": 3600
}
```

### Sample Request

<Tabs>
<Tab heading="cURL">

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/rabbitmq/config/lease
```

</Tab>
<Tab heading="CLI">

```shell-session
$ vault write rabbitmq/config/lease \
    ttl=1800 \
    max_ttl=3600
```

</Tab>
</Tabs>

## Create Role

This endpoint creates or updates the role definition.

| Method | Path                    |
| :----- | :---------------------- |
| `POST` | `/rabbitmq/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create. This
  is specified as part of the URL.

- `tags` `(string: "")` – Specifies a comma-separated RabbitMQ management tags.

- `vhosts` `(string: "")` – Specifies a map of virtual hosts to
  permissions.

- `vhost_topics` `(string: "")` – Specifies a map of virtual hosts and exchanges
  to topic permissions. This option requires RabbitMQ 3.7.0 or later.

### Sample Payload

```json
{
  "tags": "tag1,tag2",
  "vhosts": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}",
  "vhost_topics": "{\"/\": {\"amq.topic\": {\"write\":\".*\", \"read\": \".*\"}}}"
}
```

### Sample Request

<Tabs>
<Tab heading="cURL">

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/rabbitmq/roles/my-role
```

</Tab>
<Tab heading="CLI">

```shell-session
$ vault write rabbitmq/roles/my-role \
    tags="tag1,tag2" \
    vhosts="..." \
    vhost_topics="..."
```

</Tab>
</Tabs>

## Read Role

This endpoint queries the role definition.

| Method | Path                    |
| :----- | :---------------------- |
| `GET`  | `/rabbitmq/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to read. This
  is specified as part of the URL.

### Sample Request

<Tabs>
<Tab heading="cURL">

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/rabbitmq/roles/my-role
```

</Tab>
<Tab heading="CLI">

```shell-session
$ vault read rabbitmq/roles/my-role
```

</Tab>
</Tabs>

### Sample Response

```json
{
  "data": {
    "tags": "",
    "vhosts": "{\"/\": {\"configure\":\".*\", \"write\":\".*\", \"read\": \".*\"}}",
    "vhost_topics": "{\"/\": {\"amq.topic\": {\"write\":\".*\", \"read\": \".*\"}}}"
  }
}
```

## Delete Role

This endpoint deletes the role definition.

| Method   | Path                    |
| :------- | :---------------------- |
| `DELETE` | `/rabbitmq/roles/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to delete. This
  is specified as part of the URL.

### Sample Request

<Tabs>
<Tab heading="cURL">

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/rabbitmq/roles/my-role
```

</Tab>
<Tab heading="CLI">

```shell-session
vault delete rabbitmq/roles/my-role
```

</Tab>
</Tabs>

## Generate Credentials

This endpoint generates a new set of dynamic credentials based on the named
role.

| Method | Path                    |
| :----- | :---------------------- |
| `GET`  | `/rabbitmq/creds/:name` |

### Parameters

- `name` `(string: <required>)` – Specifies the name of the role to create
  credentials against. This is specified as part of the URL.

### Sample Request

<Tabs>
<Tab heading="cURL">

```shell-session
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/rabbitmq/creds/my-role
```

</Tab>
<Tab heading="CLI">

```shell-session
$ vault read rabbitmq/creds/my-role
```

</Tab>
</Tabs>

### Sample Response

```json
{
  "data": {
    "username": "root-4b95bf47-281d-dcb5-8a60-9594f8056092",
    "password": "e1b6c159-ca63-4c6a-3886-6639eae06c30"
  }
}
```