1---
2layout: "api"
3page_title: "Consul - Secrets Engines - HTTP API"
4sidebar_title: "Consul"
5sidebar_current: "api-http-secret-consul"
6description: |-
7  This is the API documentation for the Vault Consul secrets engine.
8---
9
10# Consul Secrets Engine (API)
11
12This is the API documentation for the Vault Consul secrets engine. For general
13information about the usage and operation of the Consul secrets engine, please
14see the [Vault Consul documentation](/docs/secrets/consul/index.html).
15
16This documentation assumes the Consul secrets engine is enabled at the `/consul`
17path in Vault. Since it is possible to enable secrets engines at any location,
18please update your API calls accordingly.
19
20## Configure Access
21
22This endpoint configures the access information for Consul. This access
23information is used so that Vault can communicate with Consul and generate
24Consul tokens.
25
26| Method   | Path                         |
27| :--------------------------- | :--------------------- |
28| `POST`   | `/consul/config/access`      |
29
30### Parameters
31
32- `address` `(string: <required>)` – Specifies the address of the Consul
33  instance, provided as `"host:port"` like `"127.0.0.1:8500"`.
34
35- `scheme` `(string: "http")` – Specifies the URL scheme to use.
36
37- `token` `(string: <required>)` – Specifies the Consul ACL token to use. This
38  must be a management type token.
39
40### Sample Payload
41
42```json
43{
44  "address": "127.0.0.1:8500",
45  "scheme": "https",
46  "token": "adha..."
47}
48```
49
50### Sample Request
51
52```
53$ curl \
54    --request POST \
55    --header "X-Vault-Token: ..." \
56    --data @payload.json \
57    http://127.0.0.1:8200/v1/consul/config/access
58```
59
60## Create/Update Role
61
62This endpoint creates or updates the Consul role definition. If the role does
63not exist, it will be created. If the role already exists, it will receive
64updated attributes.
65
66| Method   | Path                         |
67| :--------------------------- | :--------------------- |
68| `POST`   | `/consul/roles/:name`        |
69
70### Parameters for Consul version below 1.4
71
72- `name` `(string: <required>)` – Specifies the name of an existing role against
73  which to create this Consul credential. This is part of the request URL.
74
75- `token_type` `(string: "client")` - Specifies the type of token to create when
76  using this role. Valid values are `"client"` or `"management"`.
77
78- `policy` `(string: <policy or policies>)` – Specifies the base64 encoded ACL policy. The
79  ACL format can be found in the [Consul ACL
80  documentation](https://www.consul.io/docs/internals/acl.html). This is
81  required unless the `token_type` is `management`.
82
83- `policies` `(list: <policy or policies>)` – The list of policies to assign to the generated
84  token.  This is only available in Consul 1.4 and greater.
85
86- `local` `(bool: false)` - Indicates that the token should not be replicated
87  globally and instead be local to the current datacenter.  Only available in Consul
88  1.4 and greater.
89
90- `ttl` `(duration: "")` – Specifies the TTL for this role. This is provided
91  as a string duration with a time suffix like `"30s"` or `"1h"` or as seconds. If not
92  provided, the default Vault TTL is used.
93
94- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. This is provided
95  as a string duration with a time suffix like `"30s"` or `"1h"` or as seconds. If not
96  provided, the default Vault Max TTL is used.
97
98### Sample Payload
99
100To create management tokens:
101
102```json
103{
104  "token_type": "management"
105}
106```
107
108To create a client token with a custom policy:
109
110```json
111{
112  "policy": "abd2...=="
113}
114```
115
116### Sample Request
117
118```
119$ curl \
120    --request POST \
121    --header "X-Vault-Token: ..." \
122    --data @payload.json \
123    http://127.0.0.1:8200/v1/consul/roles/example-role
124```
125
126### Parameters for Consul versions 1.4 and above
127
128- `lease` `(string: "")` – Specifies the lease for this role. This is provided
129  as a string duration with a time suffix like `"30s"` or `"1h"`. If not
130  provided, the default Vault lease is used.
131
132- `policies` `(string: <required>)` – Comma separated list of policies to be applied
133  to the tokens.
134
135### Sample payload
136```json
137{
138  "policies": "global-management"
139}
140```
141
142### Sample request
143
144```sh
145curl \
146→     --request POST \
147→     --header "X-Vault-Token: ..."\
148→     --data @payload.json \
149→     http://127.0.0.1:8200/v1/consul/roles/example-role
150```
151
152## Read Role
153
154This endpoint queries for information about a Consul role with the given name.
155If no role exists with that name, a 404 is returned.
156
157| Method   | Path                         |
158| :--------------------------- | :--------------------- |
159| `GET`    | `/consul/roles/:name`        |
160
161### Parameters
162
163- `name` `(string: <required>)` – Specifies the name of the role to query. This
164  is part of the request URL.
165
166### Sample Request
167
168```
169$ curl \
170    --header "X-Vault-Token: ..." \
171    http://127.0.0.1:8200/v1/consul/roles/example-role
172```
173
174### Sample Response
175
176```json
177{
178  "data": {
179    "policy": "abd2...==",
180    "lease": "1h0m0s",
181    "token_type": "client"
182  }
183}
184```
185
186## List Roles
187
188This endpoint lists all existing roles in the secrets engine.
189
190| Method   | Path                         |
191| :--------------------------- | :--------------------- |
192| `LIST`   | `/consul/roles`              |
193
194### Sample Request
195
196```
197$ curl \
198    --header "X-Vault-Token: ..." \
199    --request LIST \
200    http://127.0.0.1:8200/v1/consul/roles
201```
202
203### Sample Response
204
205```json
206{
207  "data": {
208    "keys": [
209      "example-role"
210    ]
211  }
212}
213```
214
215## Delete Role
216
217This endpoint deletes a Consul role with the given name. Even if the role does
218not exist, this endpoint will still return a successful response.
219
220| Method   | Path                         |
221| :--------------------------- | :--------------------- |
222| `DELETE` | `/consul/roles/:name`        |
223
224### Parameters
225
226- `name` `(string: <required>)` – Specifies the name of the role to delete. This
227  is part of the request URL.
228
229### Sample Request
230
231```
232$ curl \
233    --request DELETE \
234    --header "X-Vault-Token: ..." \
235    http://127.0.0.1:8200/v1/consul/roles/example-role
236```
237
238## Generate Credential
239
240This endpoint generates a dynamic Consul token based on the given role
241definition.
242
243| Method   | Path                         |
244| :--------------------------- | :--------------------- |
245| `GET`    | `/consul/creds/:name`        |
246
247### Parameters
248
249- `name` `(string: <required>)` – Specifies the name of an existing role against
250  which to create this Consul credential. This is part of the request URL.
251
252### Sample Request
253
254```
255$ curl \
256    --header "X-Vault-Token: ..." \
257    http://127.0.0.1:8200/v1/consul/creds/example-role
258```
259
260### Sample Response
261
262```json
263{
264  "data": {
265    "token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
266  }
267}
268```
269