Database secrets engine (API)

This is the API documentation for the OpenBao Database secrets engine. For general information about the usage and operation of the database secrets engine, please see the OpenBao database secrets engine documentation.

This documentation assumes the database secrets engine is enabled at the /database path in OpenBao. 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 the desired database. In addition to the parameters listed here, each Database plugin has additional, database plugin specific, parameters for this endpoint. Please read the HTTP API for the plugin you'd wish to configure to see the full list of additional parameters.

warning

This endpoint distinguishes between create and update ACL capabilities.

Method	Path
`POST`	`/database/config/:name`

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.
plugin_version (string: "") - Specifies the semantic version of the plugin to use for this connection.
verify_connection (bool: true) – Specifies if the connection is verified during initial configuration. Defaults to true.
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.
password_policy (string: "") - The name of the password policy to use when generating passwords for this database. If not specified, this will use a default policy defined as: 20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character.

warning

We highly recommended that you use an OpenBao-specific user rather than the admin user in your database when configuring the plugin. This user will be used to create/update/delete users within the database so it will need to have the appropriate permissions to do so. If the plugin supports rotating the root credentials, we highly recommended you perform that action after configuring the plugin. This will change the password of the user configured in this step. The new password will not be viewable by users.

Common fields

There are several common fields that you will see across many of the database plugins. Please reference the individual plugin documentation for details on whether these fields are supported and any additional details about them.

connection_url (string) - Specifies the connection string used to connect to the database. Some plugins use url rather than connection_url. This allows for simple templating of the username and password of the root user. Typically, this is done by including a {{username}}, {{name}}, and/or {{password}} field within the string. These fields are typically be replaced with the values in the username and password fields.
username (string) - Specifies the name of the user to use as the "root" user when connecting to the database. This "root" user is used to create/update/delete users managed by these plugins, so you will need to ensure that this user has permissions to manipulate users appropriate to the database. This is typically used in the connection_url field via the templating directive {{username}} or {{name}}.
password (string) - Specifies the password to use when connecting with the username. This value will not be returned by OpenBao when performing a read upon the configuration. This is typically used in the connection_url field via the templating directive {{password}}.
disable_escaping (boolean: false) - Determines whether special characters in the username and password fields will be escaped. Useful for alternate connection string formats like ADO. More information regarding this parameter can be found on the databases secrets engine docs. Defaults to false.

Sample payload

{
  "plugin_name": "mysql-database-plugin",
  "allowed_roles": "readonly",
  "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
  "username": "openbaouser",
  "password": "secretpassword"
}

Sample cURL request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/database/config/mysql

Sample CLI request

$ openbao write database/config/mysql \
    plugin_name="mysql-database-plugin" \
    allowed_roles="readonly" \
    connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \
    username="openbaouser" \
    password="secretpassword"

Sample CLI request with ADO-style connection string

$ openbao write database/config/mysql \
    plugin_name="mysql-database-plugin" \
    connection_url='server=localhost;port=3306;user id={{username}};password={{password}};database=mysql;' \
    username="openbaouser" \
    password='your#StrongPassword%' \
    disable_escaping="true"

Read connection

This endpoint returns the configuration settings for a connection.

Method	Path
`GET`	`/database/config/:name`

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 \
    http://127.0.0.1:8200/v1/database/config/mysql

Sample response

{
  "data": {
    "allowed_roles": ["readonly"],
    "connection_details": {
      "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/",
      "username": "openbaouser"
    },
    "password_policy": "",
    "plugin_name": "mysql-database-plugin",
    "plugin_version": "",
    "root_credentials_rotate_statements": []
  }
}

List connections

This endpoint returns a list of available connections. Only the connection names are returned, not any values.

Method	Path
`LIST`	`/database/config`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/config

Sample response

{
  "data": {
    "keys": ["db-one", "db-two"]
  }
}

Delete connection

This endpoint deletes a connection.

Method	Path
`DELETE`	`/database/config/:name`

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 \
    http://127.0.0.1:8200/v1/database/config/mysql

Reset connection

This endpoint closes a connection and it's underlying plugin and restarts it with the configuration stored in the barrier.

Method	Path
`POST`	`/database/reset/:name`

Parameters

name (string: <required>) – Specifies the name of the connection to reset. 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/reset/mysql

Rotate root credentials

This endpoint is used to rotate the "root" user credentials stored for the database connection. This user must have permissions to update its own password.

Method	Path
`POST`	`/database/rotate-root/:name`

danger

Use caution: the root user's password will not be accessible once rotated so it is highly recommended that you create a user for OpenBao to utilize rather than using the actual root user.

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

Create role

This endpoint creates or updates a role definition.

warning

This endpoint distinguishes between create and update ACL capabilities.

Method	Path
`POST`	`/database/roles/:name`

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 for this role.
default_ttl (string/int: 0) - Specifies the TTL for the leases associated with this role. Accepts time suffixed strings (1h) or an integer number of seconds. Defaults to system/engine default TTL time.
max_ttl (string/int: 0) - Specifies the maximum TTL for the leases associated with this role. Accepts time suffixed strings (1h) or an integer number of seconds. Defaults to sys/mounts's 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.
creation_statements (list: <required>) – Specifies the database statements executed to create and configure a user. See the plugin's API page for more information on support and formatting for this parameter.
revocation_statements (list: []) – Specifies the database statements to be executed to revoke a user. See the plugin's API page for more information on support and formatting for this parameter.
rollback_statements (list: []) – Specifies the database statements to be executed to rollback a create operation in the event of an error. Not every plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter.
renew_statements (list: []) – Specifies the database statements to be executed to renew a user. Not every plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter.

credential_type (string: "password") – Specifies the type of credential that will be generated for the role. Options include: password, rsa_private_key, client_certificate. See the plugin's API page for credential types supported by individual databases.
credential_config (map<string|string>: <optional>) – Specifies the configuration for the given credential_type.

The following options are available for each credential_type value:
- password
  - password_policy (string: <optional>) - The policy used for password generation. If not provided, defaults to the password policy of the database configuration.
- rsa_private_key
  - key_bits (int: 2048) - The bit size of the RSA key to generate. Options include: 2048, 3072, 4096.
  - format (string: "pkcs8") - The output format of the generated private key credential. The private key will be returned from the API in PEM encoding. Options include: pkcs8.
- client_certificate
  - common_name_template (string: "") - A username template to be used for the client certificate common name.
  - ca_cert (string: "") - The PEM-encoded CA certificate.
  - ca_private_key (string: "") - The PEM-encoded private key for the given ca_cert.
  - key_type (string: <required>") - Specifies the desired key type. Options include: rsa, ed25519, ec.
  - key_bits (int: 2048) - Number of bits to use for the generated keys. Options include: 2048 (default), 3072, 4096; with key_type=ec, allowed values are: 224, 256 (default), 384, 521; ignored with key_type=ed25519.
  - signature_bits (int: 256) - The number of bits to use in the signature algorithm. Options include: 256 (default), 384, 512.

Sample payload

{
  "db_name": "mysql",
  "creation_statements": [
    "CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'",
    "GRANT SELECT ON *.* TO '{{name}}'@'%'"
  ],
  "default_ttl": "1h",
  "max_ttl": "24h"
}

Sample request

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

Read role

This endpoint queries the role definition.

Method	Path
`GET`	`/database/roles/:name`

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: ..." \
    http://127.0.0.1:8200/v1/database/roles/my-role

Sample response

{
  "data": {
    "creation_statements": [
      "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';",
      "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";"
    ],
    "credential_type": "password",
    "db_name": "mysql",
    "default_ttl": 3600,
    "max_ttl": 86400,
    "renew_statements": [],
    "revocation_statements": [],
    "rollback_statements": []
  }
}

List roles

This endpoint returns a list of available roles. Only the role names are returned, not any values.

Method	Path
`LIST`	`/database/roles`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/roles

Sample response

{
  "auth": null,
  "data": {
    "keys": ["dev", "prod"]
  },
  "lease_duration": 2764800,
  "lease_id": "",
  "renewable": false
}

Delete role

This endpoint deletes the role definition.

Method	Path
`DELETE`	`/database/roles/:name`

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 \
    http://127.0.0.1:8200/v1/database/roles/my-role

Generate credentials

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

Method	Path
`GET`	`/database/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

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/creds/my-role

Sample response

{
  "data": {
    "username": "root-1430158508-126",
    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21"
  }
}

Create static role

This endpoint creates or updates a static role definition. Static Roles are a 1-to-1 mapping of an OpenBao Role to a user in a database which are automatically rotated based on the configured rotation_period.

warning

This endpoint distinguishes between create and update ACL capabilities.

warning

OpenBao will rotate the password when creating a static role. OpenBao must do this in order to know the password.

Method	Path
`POST`	`/database/static-roles/:name`

Parameters

name (string: <required>) – Specifies the name of the role to create. This is specified as part of the URL.
username (string: <required>) – Specifies the database username that this OpenBao role corresponds to.
rotation_period (string/int: <required>) – Specifies the amount of time OpenBao should wait before rotating the password. The minimum is 5 seconds.
db_name (string: <required>) - The name of the database connection to use for this role.
rotation_statements (list: []) – Specifies the database statements to be executed to rotate the password for the configured database user. Not every plugin type will support this functionality. See the plugin's API page for more information on support and formatting for this parameter.

credential_type (string: "password") – Specifies the type of credential that will be generated for the role. Options include: password, rsa_private_key, client_certificate. See the plugin's API page for credential types supported by individual databases.
credential_config (map<string|string>: <optional>) – Specifies the configuration for the given credential_type.

The following options are available for each credential_type value:
- password
  - password_policy (string: <optional>) - The policy used for password generation. If not provided, defaults to the password policy of the database configuration.
- rsa_private_key
  - key_bits (int: 2048) - The bit size of the RSA key to generate. Options include: 2048, 3072, 4096.
  - format (string: "pkcs8") - The output format of the generated private key credential. The private key will be returned from the API in PEM encoding. Options include: pkcs8.
- client_certificate
  - common_name_template (string: "") - A username template to be used for the client certificate common name.
  - ca_cert (string: "") - The PEM-encoded CA certificate.
  - ca_private_key (string: "") - The PEM-encoded private key for the given ca_cert.
  - key_type (string: <required>") - Specifies the desired key type. Options include: rsa, ed25519, ec.
  - key_bits (int: 2048) - Number of bits to use for the generated keys. Options include: 2048 (default), 3072, 4096; with key_type=ec, allowed values are: 224, 256 (default), 384, 521; ignored with key_type=ed25519.
  - signature_bits (int: 256) - The number of bits to use in the signature algorithm. Options include: 256 (default), 384, 512.

Sample payload

{
  "db_name": "mysql",
  "username": "static-database-user",
  "rotation_statements": [
    "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
  ],
  "rotation_period": "1h"
}

Sample request

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

Read static role

This endpoint queries the static role definition.

Method	Path
`GET`	`/database/static-roles/:name`

Parameters

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

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/static-roles/my-static-role

Sample response

{
  "data": {
    "credential_type": "password",
    "db_name": "mysql",
    "username": "static-user",
    "rotation_statements": [
      "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';"
    ],
    "rotation_period": "1h"
  }
}

List static roles

This endpoint returns a list of available static roles. Only the role names are returned, not any values.

Method	Path
`LIST`	`/database/static-roles`

Parameters

after (string: "") - Optional entry to begin listing after for pagination; not required to exist.
limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/database/static-roles

Sample response

{
  "auth": null,
  "data": {
    "keys": ["dev-static", "prod-static"]
  }
}

Delete static role

This endpoint deletes the static role definition. The user, having been defined externally, must be cleaned up manually.

Method	Path
`DELETE`	`/database/static-roles/:name`

Parameters

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

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/database/static-roles/my-role

Get static credentials

This endpoint returns the current credentials based on the named static role.

Method	Path
`GET`	`/database/static-creds/:name`

Parameters

name (string: <required>) – Specifies the name of the static role to get credentials for. This is specified as part of the URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/database/static-creds/my-static-role

Sample response

{
  "data": {
    "username": "static-user",
    "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21",
    "last_openbao_rotation": "2019-05-06T15:26:42.525302-05:00",
    "rotation_period": 30,
    "ttl": 28
  }
}

Rotate static role credentials

This endpoint is used to rotate the Static Role credentials stored for a given role name. While Static Roles are rotated automatically by OpenBao at configured rotation periods, users can use this endpoint to manually trigger a rotation to change the stored password and reset the TTL of the Static Role's password.

Method	Path
`POST`	`/database/rotate-role/:name`

Parameters

name (string: <required>) – Specifies the name of the Static Role to trigger the password rotation for. The name 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-role/my-static-role

Configure connection​

Parameters​

Common fields​

Sample payload​

Sample cURL request​

Sample CLI request​

Sample CLI request with ADO-style connection string​

Read connection​

Parameters​

Sample request​

Sample response​

List connections​

Sample request​

Sample response​

Delete connection​

Parameters​

Sample request​

Reset connection​

Parameters​

Sample request​

Rotate root credentials​

Parameters​

Sample request​

Create role​

Parameters​

Sample payload​

Sample request​

Read role​

Parameters​

Sample request​

Sample response​

List roles​

Parameters​

Sample request​

Sample response​

Delete role​

Parameters​

Sample request​

Generate credentials​

Parameters​

Sample request​

Sample response​

Create static role​

Parameters​

Sample payload​

Sample request​

Read static role​

Parameters​

Sample request​

Sample response​

List static roles​

Parameters​

Sample request​

Sample response​

Delete static role​

Parameters​

Sample request​

Get static credentials​

Parameters​

Sample request​

Sample response​

Rotate static role credentials​

Parameters​

Sample request​

Configure connection

Parameters

Common fields

Sample payload

Sample cURL request

Sample CLI request

Sample CLI request with ADO-style connection string

Read connection

Parameters

Sample request

Sample response

List connections

Sample request

Sample response

Delete connection

Parameters

Sample request

Reset connection

Parameters

Sample request

Rotate root credentials

Parameters

Sample request

Create role

Parameters

Sample payload

Sample request

Read role

Parameters

Sample request

Sample response

List roles

Parameters

Sample request

Sample response

Delete role

Parameters

Sample request

Generate credentials

Parameters

Sample request

Sample response

Create static role

Parameters

Sample payload

Sample request

Read static role

Parameters

Sample request

Sample response

List static roles

Parameters

Sample request

Sample response

Delete static role

Parameters

Sample request

Get static credentials

Parameters

Sample request

Sample response

Rotate static role credentials

Parameters

Sample request