2017-05-03 09:13:07 +00:00
---
layout: "api"
2017-09-20 20:05:00 +00:00
page_title: "Database - Secrets Engines - HTTP API"
New Docs Website (#5535)
* conversion stage 1
* correct image paths
* add sidebar title to frontmatter
* docs/concepts and docs/internals
* configuration docs and multi-level nav corrections
* commands docs, index file corrections, small item nav correction
* secrets converted
* auth
* add enterprise and agent docs
* add extra dividers
* secret section, wip
* correct sidebar nav title in front matter for apu section, start working on api items
* auth and backend, a couple directory structure fixes
* remove old docs
* intro side nav converted
* reset sidebar styles, add hashi-global-styles
* basic styling for nav sidebar
* folder collapse functionality
* patch up border length on last list item
* wip restructure for content component
* taking middleman hacking to the extreme, but its working
* small css fix
* add new mega nav
* fix a small mistake from the rebase
* fix a content resolution issue with middleman
* title a couple missing docs pages
* update deps, remove temporary markup
* community page
* footer to layout, community page css adjustments
* wip downloads page
* deps updated, downloads page ready
* fix community page
* homepage progress
* add components, adjust spacing
* docs and api landing pages
* a bunch of fixes, add docs and api landing pages
* update deps, add deploy scripts
* add readme note
* update deploy command
* overview page, index title
* Update doc fields
Note this still requires the link fields to be populated -- this is solely related to copy on the description fields
* Update api_basic_categories.yml
Updated API category descriptions. Like the document descriptions you'll still need to update the link headers to the proper target pages.
* Add bottom hero, adjust CSS, responsive friendly
* Add mega nav title
* homepage adjustments, asset boosts
* small fixes
* docs page styling fixes
* meganav title
* some category link corrections
* Update API categories page
updated to reflect the second level headings for api categories
* Update docs_detailed_categories.yml
Updated to represent the existing docs structure
* Update docs_detailed_categories.yml
* docs page data fix, extra operator page remove
* api data fix
* fix makefile
* update deps, add product subnav to docs and api landing pages
* Rearrange non-hands-on guides to _docs_
Since there is no place for these on learn.hashicorp, we'll put them
under _docs_.
* WIP Redirects for guides to docs
* content and component updates
* font weight hotfix, redirects
* fix guides and intro sidenavs
* fix some redirects
* small style tweaks
* Redirects to learn and internally to docs
* Remove redirect to `/vault`
* Remove `.html` from destination on redirects
* fix incorrect index redirect
* final touchups
* address feedback from michell for makefile and product downloads
2018-10-19 15:40:11 +00:00
sidebar_title: "Databases"
sidebar_current: "api-http-secret-databases"
2017-05-03 09:13:07 +00:00
description: |-
2017-09-20 20:05:00 +00:00
Top page for database secrets engine information
2017-05-03 09:13:07 +00:00
---
2017-09-20 20:05:00 +00:00
# Database Secrets Engine (API)
2017-05-03 09:13:07 +00:00
2017-09-20 20:05:00 +00:00
This is the API documentation for the Vault Database secrets engine. For
general information about the usage and operation of the database secrets engine,
2017-05-03 09:13:07 +00:00
please see the
2017-09-20 20:05:00 +00:00
[Vault database secrets engine documentation ](/docs/secrets/databases/index.html ).
2017-05-03 09:13:07 +00:00
2017-09-20 20:05:00 +00:00
This documentation assumes the database secrets engine is enabled at the
`/database` path in Vault. Since it is possible to enable secrets engines at any
location, please update your API calls accordingly.
2017-05-03 09:13:07 +00:00
## Configure Connection
This endpoint configures the connection string used to communicate with the
desired database. In addition to the parameters listed here, each Database
2018-01-03 15:38:55 +00:00
plugin has additional, database plugin specific, parameters for this endpoint.
2017-05-03 09:13:07 +00:00
Please read the HTTP API for the plugin you'd wish to configure to see the full
list of additional parameters.
2018-06-19 15:24:28 +00:00
~> This endpoint distinguishes between `create` and `update` ACL capabilities.
2017-05-03 09:13:07 +00:00
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name for this database
connection. This is specified as part of the URL.
- `plugin_name` `(string: <required>)` - Specifies the name of the plugin to use
for this connection.
- `verify_connection` `(bool: true)` – Specifies if the connection is verified
during initial configuration. Defaults to true.
2018-04-09 16:20:29 +00:00
- `allowed_roles` `(list: [])` - List of the roles allowed to use this connection.
Defaults to empty (no roles), if contains a "*" any role can use this connection.
- `root_rotation_statements` `(list: [])` - Specifies the database statements to be
executed to rotate the root user's credentials. See the plugin's API page for more
information on support and formatting for this parameter.
2017-05-03 09:13:07 +00:00
### Sample Payload
```json
{
"plugin_name": "mysql-database-plugin",
"allowed_roles": "readonly",
2018-04-09 16:20:29 +00:00
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"username": "root",
"password": "mysql"
2017-05-03 09:13:07 +00:00
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload .json \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/config/mysql
2017-05-03 09:13:07 +00:00
```
## Read Connection
This endpoint returns the configuration settings for a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/database/config/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to read.
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request GET \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/config/mysql
2017-05-03 09:13:07 +00:00
```
### Sample Response
```json
{
"data": {
"allowed_roles": [
"readonly"
],
"connection_details": {
2018-04-09 16:20:29 +00:00
"connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
"username": "root"
2017-05-03 09:13:07 +00:00
},
"plugin_name": "mysql-database-plugin"
},
}
```
2018-02-22 20:27:33 +00:00
## List Connections
This endpoint returns a list of available connections. Only the connection names
are returned, not any values.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/database/config` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/config
2018-02-22 20:27:33 +00:00
```
### Sample Response
```json
{
"data": {
"keys": ["db-one", "db-two"]
}
}
```
2017-05-03 09:13:07 +00:00
## Delete Connection
This endpoint deletes a connection.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/database/config/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to delete.
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/config/mysql
2017-05-03 09:13:07 +00:00
```
## Reset Connection
This endpoint closes a connection and it's underlying plugin and restarts it
with the configuration stored in the barrier.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/reset/:name` | `204 (empty body)` |
### Parameters
2018-10-15 13:47:43 +00:00
- `name` `(string: <required>)` – Specifies the name of the connection to reset.
2017-05-03 09:13:07 +00:00
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/reset/mysql
2017-05-03 09:13:07 +00:00
```
2018-04-09 16:20:29 +00:00
## Rotate Root Credentials
This endpoint is used to rotate the root superuser credentials stored for
the database connection. This user must have permissions to update its own
password.
| Method | Path | Produces |
| :------- | :---------------------------- | :--------------------- |
| `POST` | `/database/rotate-root/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the connection to rotate.
This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/database/rotate-root/mysql
```
2017-05-03 09:13:07 +00:00
## Create Role
This endpoint creates or updates a role definition.
2018-06-19 15:24:28 +00:00
~> This endpoint distinguishes between `create` and `update` ACL capabilities.
2017-05-03 09:13:07 +00:00
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `POST` | `/database/roles/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create. This
is specified as part of the URL.
- `db_name` `(string: <required>)` - The name of the database connection to use
2017-09-13 01:48:52 +00:00
for this role.
2017-05-03 09:13:07 +00:00
2017-05-04 18:45:27 +00:00
- `default_ttl` `(string/int: 0)` - Specifies the TTL for the leases
associated with this role. Accepts time suffixed strings ("1h") or an integer
2017-09-20 20:05:00 +00:00
number of seconds. Defaults to system/engine default TTL time.
2017-05-03 09:13:07 +00:00
2017-05-04 18:45:27 +00:00
- `max_ttl` `(string/int: 0)` - Specifies the maximum TTL for the leases
associated with this role. Accepts time suffixed strings ("1h") or an integer
2018-10-29 19:19:35 +00:00
number of seconds. Defaults to system/mount default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. See also [The TTL General Case ](https://www.vaultproject.io/docs/concepts/tokens.html#the-general-case ).
2017-05-03 09:13:07 +00:00
2018-04-09 16:20:29 +00:00
- `creation_statements` `(list: <required>)` – Specifies the database
2017-05-11 18:59:58 +00:00
statements executed to create and configure a user. See the plugin's API page
2017-09-13 01:48:52 +00:00
for more information on support and formatting for this parameter.
2017-05-03 09:13:07 +00:00
2018-04-09 16:20:29 +00:00
- `revocation_statements` `(list: [])` – Specifies the database statements to
2017-05-11 18:59:58 +00:00
be executed to revoke a user. See the plugin's API page for more information
2017-09-13 01:48:52 +00:00
on support and formatting for this parameter.
2017-05-03 09:13:07 +00:00
2018-04-09 16:20:29 +00:00
- `rollback_statements` `(list: [])` – Specifies the database statements to be
2017-05-03 09:13:07 +00:00
executed rollback a create operation in the event of an error. Not every
2017-05-11 18:59:58 +00:00
plugin type will support this functionality. See the plugin's API page for
2017-09-13 01:48:52 +00:00
more information on support and formatting for this parameter.
2017-05-03 09:13:07 +00:00
2018-04-09 16:20:29 +00:00
- `renew_statements` `(list: [])` – Specifies the database statements to be
2017-05-03 09:13:07 +00:00
executed to renew a user. Not every plugin type will support this
2017-05-11 18:59:58 +00:00
functionality. See the plugin's API page for more information on support and
2017-09-13 01:48:52 +00:00
formatting for this parameter.
2017-05-11 18:59:58 +00:00
2017-05-03 09:13:07 +00:00
### Sample Payload
```json
{
"db_name": "mysql",
2018-04-09 16:20:29 +00:00
"creation_statements": ["CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'", "GRANT SELECT ON *.* TO '{{name}}'@'%'"],
2017-05-03 09:13:07 +00:00
"default_ttl": "1h",
"max_ttl": "24h"
}
```
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload .json \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/roles/my-role
2017-05-03 09:13:07 +00:00
```
## Read Role
This endpoint queries the role definition.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/database/roles/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to read. This
is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/roles/my-role
2017-05-03 09:13:07 +00:00
```
### Sample Response
```json
{
"data": {
2018-04-09 16:20:29 +00:00
"creation_statements": ["CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';"], "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"],
2017-05-03 09:13:07 +00:00
"db_name": "mysql",
"default_ttl": 3600,
"max_ttl": 86400,
2018-04-09 16:20:29 +00:00
"renew_statements": [],
"revocation_statements": [],
"rollback_statements": []
2017-05-03 09:13:07 +00:00
},
}
```
## List Roles
This endpoint returns a list of available roles. Only the role names are
returned, not any values.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/database/roles` | `200 application/json` |
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/roles
2017-05-03 09:13:07 +00:00
```
### Sample Response
```json
{
"auth": null,
"data": {
"keys": ["dev", "prod"]
},
"lease_duration": 2764800,
"lease_id": "",
"renewable": false
}
```
## Delete Role
This endpoint deletes the role definition.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `DELETE` | `/database/roles/:name` | `204 (empty body)` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to delete. This
is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/roles/my-role
2017-05-03 09:13:07 +00:00
```
## Generate Credentials
This endpoint generates a new set of dynamic credentials based on the named
role.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `GET` | `/database/creds/:name` | `200 application/json` |
### Parameters
- `name` `(string: <required>)` – Specifies the name of the role to create
credentials against. This is specified as part of the URL.
### Sample Request
```
$ curl \
--header "X-Vault-Token: ..." \
2018-03-23 15:41:51 +00:00
http://127.0.0.1:8200/v1/database/creds/my-role
2017-05-03 09:13:07 +00:00
```
### Sample Response
```json
{
"data": {
"username": "root-1430158508-126",
"password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
}
}
```