1---
2layout: "api"
3page_title: "MongoDB - Secrets Engines - HTTP API"
4sidebar_title: "MongoDB <sup>DEPRECATED</sup>"
5sidebar_current: "api-http-secret-mongodb"
6description: |-
7  This is the API documentation for the Vault MongoDB secrets engine.
8---
9
10# MongoDB Secrets Engine (API)
11
12~> **Deprecation Note:** This secrets engine is deprecated in favor of the
13combined databases secrets engine added in v0.7.1. See the API documentation for
14the new implementation of this secrets engine at
15[MongoDB database plugin HTTP API](/api/secret/databases/mongodb.html).
16
17This is the API documentation for the Vault MongoDB secrets engine. For general
18information about the usage and operation of the MongoDB secrets engine, please
19see the
20[Vault MongoDB secrets engine documentation](/docs/secrets/mongodb/index.html).
21
22This documentation assumes the MongoDB secrets engine is enabled at the
23`/mongodb` path in Vault. Since it is possible to enable secrets engines at any
24location, please update your API calls accordingly.
25
26## Configure Connection
27
28This endpoint configures the standard connection string (URI) used to
29communicate with MongoDB.
30
31| Method   | Path                         |
32| :--------------------------- | :--------------------- |
33| `POST`   | `/mongodb/config/connection` |
34
35### Parameters
36
37- `url` `(string: <required>)` – Specifies the MongoDB standard connection
38  string (URI).
39
40- `verify_connection` `(bool: true)` – Specifies if the connection is verified
41  during initial configuration.
42
43### Sample Payload
44
45```json
46{
47  "url": "mongodb://db1.example.net,db2.example.net:2500/?replicaSet=test"
48}
49```
50
51### Sample Request
52
53```
54$ curl \
55    --header "X-Vault-Token: ..." \
56    --request POST \
57    --data @payload.json \
58    http://127.0.0.1:8200/v1/mongodb/config/connection
59```
60
61### Sample Response
62
63```json
64{
65  "lease_id": "",
66  "renewable": false,
67  "lease_duration": 0,
68  "data": null,
69  "wrap_info": null,
70  "warnings": [
71    "Read access to this endpoint should be controlled via ACLs as it will return the connection URI as it is, including passwords, if any."
72  ],
73  "auth": null
74}
75```
76
77## Read Connection
78
79This endpoint queries the connection configuration. Access to this endpoint
80should be controlled via ACLs as it will return the connection URI as it is,
81including passwords, if any.
82
83| Method   | Path                         |
84| :--------------------------- | :--------------------- |
85| `GET`    | `/mongodb/config/connection` |
86
87### Sample Request
88
89```
90$ curl \
91    --header "X-Vault-Token: ..." \
92    http://127.0.0.1:8200/v1/mongodb/config/connection
93```
94
95### Sample Response
96
97```json
98{
99  "lease_id": "",
100  "renewable": false,
101  "lease_duration": 0,
102  "data": {
103    "uri": "mongodb://admin:Password!@mongodb.acme.com:27017/admin?ssl=true"
104  },
105  "wrap_info": null,
106  "warnings": null,
107  "auth": null
108}
109```
110
111## Configure Lease
112
113This endpoint configures the default lease TTL settings for credentials
114generated by the mongodb secrets engine.
115
116| Method   | Path                         |
117| :--------------------------- | :--------------------- |
118| `POST`   | `/mongodb/config/lease`      |
119
120### Parameters
121
122- `lease` `(string: <required>)` – Specifies the lease value provided as a
123  string duration with time suffix. "h" (hour) is the largest suffix.
124
125- `lease_max` `(string: <required>)` – Specifies the maximum lease value
126  provided as a string duration with time suffix. "h" (hour) is the largest
127  suffix.
128
129### Sample Payload
130
131```json
132{
133  "lease": "12h",
134  "lease_max": "24h"
135}
136```
137
138### Sample Request
139
140```
141$ curl \
142    --header "X-Vault-Token: ..." \
143    --request POST \
144    --data @payload.json \
145    http://127.0.0.1:8200/v1/mongodb/config/lease
146```
147
148## Read Lease
149
150This endpoint queries the lease configuration.
151
152| Method   | Path                         |
153| :--------------------------- | :--------------------- |
154| `GET`    | `/mongodb/config/lease`      |
155
156### Sample Request
157
158```
159$ curl \
160    --header "X-Vault-Token: ..." \
161    http://127.0.0.1:8200/v1/mongodb/config/lease
162```
163
164### Sample Response
165
166```json
167{
168  "lease_id": "",
169  "renewable": false,
170  "lease_duration": 0,
171  "data": {
172    "max_ttl": 60,
173    "ttl": 60
174  },
175  "wrap_info": null,
176  "warnings": null,
177  "auth": null
178}
179```
180
181## Create Role
182
183This endpoint creates or updates a role definition.
184
185| Method   | Path                         |
186| :--------------------------- | :--------------------- |
187| `POST`   | `/mongodb/roles/:name`       |
188
189### Parameters
190
191- `db` `(string: <required>)` – Specifies the name of the database users should
192  be created in for this role.
193
194- `roles` `(string: "")` – Specifies the MongoDB roles to assign to the users
195  generated for this role.
196
197### Sample Payload
198
199```json
200{
201  "db": "my-db",
202  "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]"
203}
204```
205
206### Sample Request
207
208```
209$ curl \
210    --header "X-Vault-Token: ..." \
211    --request POST \
212    --data @payload.json \
213    http://127.0.0.1:8200/v1/mongodb/roles/my-role
214```
215
216## Read Role
217
218This endpoint queries the role definition.
219
220| Method   | Path                         |
221| :--------------------------- | :--------------------- |
222| `GET`    | `/mongodb/roles/:name`       |
223
224### Parameters
225
226- `name` `(string: <required>)` – Specifies the name of the role to read. This
227  is specified as part of the URL.
228
229### Sample Request
230
231```
232$ curl \
233    --header "X-Vault-Token: ..." \
234    http://127.0.0.1:8200/v1/mongodb/roles/my-role
235```
236
237### Sample Response
238
239```json
240{
241  "lease_id": "",
242  "renewable": false,
243  "lease_duration": 0,
244  "data": {
245    "db": "foo",
246    "roles": "[\"readWrite\",{\"db\":\"bar\",\"role\":\"read\"}]"
247  },
248  "wrap_info": null,
249  "warnings": null,
250  "auth": null
251}
252```
253
254## List Roles
255
256This endpoint returns a list of available roles. Only the role names are
257returned, not any values.
258
259| Method   | Path                         |
260| :--------------------------- | :--------------------- |
261| `LIST`   | `/mongodb/roles`             |
262
263### Sample Request
264
265```
266$ curl \
267    --header "X-Vault-Token: ..." \
268    --request LIST \
269    http://127.0.0.1:8200/v1/mongodb/roles
270```
271
272### Sample Response
273
274```json
275{
276  "lease_id": "",
277  "renewable": false,
278  "lease_duration": 0,
279  "data": {
280    "keys": [
281      "dev",
282      "prod"
283    ]
284  },
285  "wrap_info": null,
286  "warnings": null,
287  "auth": null
288}
289```
290
291## Delete Role
292
293This endpoint deletes the role definition.
294
295| Method   | Path                         |
296| :--------------------------- | :--------------------- |
297| `DELETE` | `/mongodb/roles/:name`       |
298
299### Parameters
300
301- `name` `(string: <required>)` – Specifies the name of the role to delete. This
302  is specified as part of the URL.
303
304### Sample Request
305
306```
307$ curl \
308    --header "X-Vault-Token: ..." \
309    --request DELETE \
310    http://127.0.0.1:8200/v1/mongodb/roles/my-role
311```
312
313## Generate Credentials
314
315This endpoint generates a new set of dynamic credentials based on the named
316role.
317
318| Method   | Path                         |
319| :--------------------------- | :--------------------- |
320| `GET`    | `/mongodb/creds/:name`       |
321
322### Parameters
323
324- `name` `(string: <required>)` – Specifies the name of the role to create
325  credentials against. This is specified as part of the URL.
326
327### Sample Request
328
329```
330$ curl \
331    --header "X-Vault-Token: ..." \
332    http://127.0.0.1:8200/v1/mongodb/creds/my-role
333```
334
335### Sample Response
336
337```json
338{
339  "lease_id": "mongodb/creds/readonly/e64e79d8-9f56-e379-a7c5-373f9b4ee3d8",
340  "renewable": true,
341  "lease_duration": 3600,
342  "data": {
343    "db": "foo",
344    "password": "de0f7b50-d700-54e5-4e81-5c3724283999",
345    "username": "vault-token-b32098cb-7ff2-dcf5-83cd-d5887cedf81b"
346  },
347  "wrap_info": null,
348  "warnings": null,
349  "auth": null
350}
351```
352