v1.14.6/website/content/api-docs/secret/consul.mdx - hashicorp/vault - Git at Google

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

 # Consul secrets engine (API)

 @include 'x509-sha1-deprecation.mdx'

 @include 'consul-dataplane-compat.mdx'

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

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

 ## Configure access

 This endpoint configures the access information for Consul. This access
 information is used so that Vault can communicate with Consul and generate
 Consul tokens.

 | Method | Path                    |
 | :----- | :---------------------- |
 | `POST` | `/consul/config/access` |

 ### Parameters

 - `address` `(string: <required>)` – Specifies the address of the Consul
   instance, provided as `"host:port"` like `"127.0.0.1:8500"`.

 - `scheme` `(string: "http")` – Specifies the URL scheme to use.

 - `token` `(string: "")` – Specifies the Consul ACL token to use. This
   must be a management type token. If this is not provided, Vault will try to
   bootstrap the ACL system of the Consul cluster automatically.

 - `ca_cert` `(string: "")` - CA certificate to use when verifying Consul server certificate,
   must be x509 PEM encoded.

 - `client_cert` `(string: "")` - Client certificate used for Consul's TLS communication,
   must be x509 PEM encoded and if this is set you need to also set client_key.

 - `client_key` `(string: "")` - Client key used for Consul's TLS communication,
   must be x509 PEM encoded and if this is set you need to also set client_cert.

 ### Sample payload

 ```json
 {
   "address": "127.0.0.1:8500",
   "scheme": "https",
   "token": "adha..."
 }
 ```

 ### Sample request

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

 ## Create/Update role

 This endpoint creates or updates the Consul role definition. If the role does
 not exist, it will be created. If the role already exists, it will receive
 updated attributes. At least one of `consul_policies`, `consul_roles`,
 `service_identities`, or `node_identities` is required depending on the
 Consul version.

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

 ### Parameters for consul versions 1.11 and above

 - `partition` `(string: "")` - Specifies the Consul admin partition in which the token is generated.
   The partition must exist, and the Consul policies or roles assigned to the
   Vault role must also exist inside the given partition. If not provided, the partition `default`
   is used.

 To create a client token within a particular Consul admin partition:

 ```json
 {
   "partition": "admin1"
 }
 ```

 ### Parameters for consul versions 1.8 and above

 - `node_identities` `(list: <node identity or identities>)` - The list of node identities to assign to the generated
   token. This may be a comma-separated list to attach multiple node identities to a token.

 To create a client token with node identities attached:

 ```json
 {
   "node_identities": [
       "client-1:dc1",
       "client-2:dc1"
     ]
 }
 ```

 ### Parameters for consul versions 1.7 and above

 - `consul_namespace` `(string: "")` - Specifies the Consul namespace in which the token is generated.
   The namespace must exist, and the Consul policies or roles assigned to the Vault role must also exist
   inside the given Consul namespace. If not provided, the namespace `default` is used.

 To create a client token within a particular Consul namespace:

 ```json
 {
   "consul_namespace": "ns1"
 }
 ```

 ### Parameters for consul version 1.5 and above

 - `service_identities` `(list: <service identity or identities>)` - The list of service identities to assign to the generated
   token. This may be a comma-separated list to attach multiple service identities to a token.

 - `consul_roles` `(list: <role or roles>)` – The list of Consul roles to attach to the
   token generated by Vault.

   To create a client token with roles defined in Consul:

 ### Sample payload

 ```json
 {
   "consul_roles": "role-a,role-b"
 }
 ```

 To create a client token with service identities attached:

 ```json
 {
   "service_identities": [
       "myservice-1:dc1,dc2",
       "myservice-2:dc1"
     ]
 }
 ```

 ### Parameters for consul versions 1.4 and above

 - `name` `(string: <required>)` – Specifies the name of an existing role against
   which to create this Consul credential. This is part of the request URL.

 - `token_type` <sup>DEPRECATED (1.11)</sup> `(string: "client")` - Specifies the type of token to create
   when using this role. Valid values are `"client"` or `"management"`. If a `"management"`
   token, the `policy` parameter is not required. Defaults to `"client`". [Deprecated from Consul as of 1.4 and
   removed as of Consul 1.11.](/consul/api-docs/acl/legacy)

 - `policy` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the base64-encoded ACL policy.
   This is required unless the `token_type` is `"management"`. [Deprecated from Consul as of 1.4 and
   removed as of Consul 1.11.](/consul/api-docs/acl/legacy)

 - `policies` <sup>DEPRECATED (1.11)</sup> `(list: <policy or policies>)` - Same as `consul_policies`.
   Deprecated in favor of using `consul_policies`.

 - `consul_policies` `(list: <policy or policies>)` – The list of Consul policies to assign
   to the generated token. This field is required if using using Consul 1.4.

 - `local` `(bool: false)` - Indicates that the token should not be replicated
   globally and instead be local to the current datacenter. Only available in Consul
   1.4 and greater.

 - `ttl` `(duration: "")` – Specifies the TTL for this role. If not
   provided, the default Vault TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format).

 - `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not
   provided, the default Vault Max TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format).

 ### Sample payload

 To create a client token with policies defined in Consul:

 ```json
 {
   "consul_policies": "policy-1,policy-2"
 }
 ```

 ### Parameters for consul version below 1.4

 - `lease` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the lease for this role.
   Uses [duration format strings](/vault/docs/concepts/duration-format). If not
   provided, the default Vault lease is used.

 - `policy` <sup>DEPRECATED (1.11)</sup> `(string: <policy>)` – Specifies the base64-encoded ACL policy. The
   ACL format can be found in the [Consul ACL
   documentation](/consul/docs/security/acl/acl-legacy). This is
   required unless the `token_type` is `"management"`.

 ### Sample payload

 To create a client token with a base64-encoded policy:

 ```json
 {
   "policy": "a2V5ICIi...=="
 }
 ```

 To create management tokens:

 ```json
 {
   "token_type": "management"
 }
 ```

 ### Sample request

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

 ## Read role

 This endpoint queries for information about a Consul role with the given name.
 If no role exists with that name, a 404 is returned.

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

 ### Parameters

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

 ### Sample request

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

 ### Sample response

 ```json
 {
   "data": {
     "policy": "abd2...==",
     "lease": "1h0m0s",
     "token_type": "client"
   }
 }
 ```

 ## List roles

 This endpoint lists all existing roles in the secrets engine.

 | Method | Path            |
 | :----- | :-------------- |
 | `LIST` | `/consul/roles` |

 ### Sample request

 ```shell-session
 $ curl \
     --header "X-Vault-Token: ..." \
     --request LIST \
     http://127.0.0.1:8200/v1/consul/roles
 ```

 ### Sample response

 ```json
 {
   "data": {
     "keys": ["example-role"]
   }
 }
 ```

 ## Delete role

 This endpoint deletes a Consul role with the given name. Even if the role does
 not exist, this endpoint will still return a successful response.

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

 ### Parameters

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

 ### Sample request

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

 ## Generate credential

 This endpoint generates a dynamic Consul token based on the given role
 definition.

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

 ### Parameters

 - `name` `(string: <required>)` – Specifies the name of an existing role against
   which to create this Consul credential. This is part of the request URL.

 ### Sample request

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

 ### Sample response

 ```json
 {
   "data": {
     "token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
   }
 }
 ```
	---
	layout: api
	page_title: Consul - Secrets Engines - HTTP API
	description: This is the API documentation for the Vault Consul secrets engine.
	---

	# Consul secrets engine (API)

	@include 'x509-sha1-deprecation.mdx'

	@include 'consul-dataplane-compat.mdx'

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

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

	## Configure access

	This endpoint configures the access information for Consul. This access
	information is used so that Vault can communicate with Consul and generate
	Consul tokens.

	\| Method \| Path \|
	\| :----- \| :---------------------- \|
	\| `POST` \| `/consul/config/access` \|

	### Parameters

	- `address` `(string: <required>)` – Specifies the address of the Consul
	instance, provided as `"host:port"` like `"127.0.0.1:8500"`.

	- `scheme` `(string: "http")` – Specifies the URL scheme to use.

	- `token` `(string: "")` – Specifies the Consul ACL token to use. This
	must be a management type token. If this is not provided, Vault will try to
	bootstrap the ACL system of the Consul cluster automatically.

	- `ca_cert` `(string: "")` - CA certificate to use when verifying Consul server certificate,
	must be x509 PEM encoded.

	- `client_cert` `(string: "")` - Client certificate used for Consul's TLS communication,
	must be x509 PEM encoded and if this is set you need to also set client_key.

	- `client_key` `(string: "")` - Client key used for Consul's TLS communication,
	must be x509 PEM encoded and if this is set you need to also set client_cert.

	### Sample payload

	```json
	{
	"address": "127.0.0.1:8500",
	"scheme": "https",
	"token": "adha..."
	}
	```

	### Sample request

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

	## Create/Update role

	This endpoint creates or updates the Consul role definition. If the role does
	not exist, it will be created. If the role already exists, it will receive
	updated attributes. At least one of `consul_policies`, `consul_roles`,
	`service_identities`, or `node_identities` is required depending on the
	Consul version.

	\| Method \| Path \|
	\| :----- \| :-------------------- \|
	\| `POST` \| `/consul/roles/:name` \|

	### Parameters for consul versions 1.11 and above

	- `partition` `(string: "")` - Specifies the Consul admin partition in which the token is generated.
	The partition must exist, and the Consul policies or roles assigned to the
	Vault role must also exist inside the given partition. If not provided, the partition `default`
	is used.

	To create a client token within a particular Consul admin partition:

	```json
	{
	"partition": "admin1"
	}
	```

	### Parameters for consul versions 1.8 and above

	- `node_identities` `(list: <node identity or identities>)` - The list of node identities to assign to the generated
	token. This may be a comma-separated list to attach multiple node identities to a token.

	To create a client token with node identities attached:

	```json
	{
	"node_identities": [
	"client-1:dc1",
	"client-2:dc1"
	]
	}
	```

	### Parameters for consul versions 1.7 and above

	- `consul_namespace` `(string: "")` - Specifies the Consul namespace in which the token is generated.
	The namespace must exist, and the Consul policies or roles assigned to the Vault role must also exist
	inside the given Consul namespace. If not provided, the namespace `default` is used.

	To create a client token within a particular Consul namespace:

	```json
	{
	"consul_namespace": "ns1"
	}
	```

	### Parameters for consul version 1.5 and above

	- `service_identities` `(list: <service identity or identities>)` - The list of service identities to assign to the generated
	token. This may be a comma-separated list to attach multiple service identities to a token.

	- `consul_roles` `(list: <role or roles>)` – The list of Consul roles to attach to the
	token generated by Vault.

	To create a client token with roles defined in Consul:

	### Sample payload

	```json
	{
	"consul_roles": "role-a,role-b"
	}
	```

	To create a client token with service identities attached:

	```json
	{
	"service_identities": [
	"myservice-1:dc1,dc2",
	"myservice-2:dc1"
	]
	}
	```

	### Parameters for consul versions 1.4 and above

	- `name` `(string: <required>)` – Specifies the name of an existing role against
	which to create this Consul credential. This is part of the request URL.

	- `token_type` <sup>DEPRECATED (1.11)</sup> `(string: "client")` - Specifies the type of token to create
	when using this role. Valid values are `"client"` or `"management"`. If a `"management"`
	token, the `policy` parameter is not required. Defaults to `"client`". [Deprecated from Consul as of 1.4 and
	removed as of Consul 1.11.](/consul/api-docs/acl/legacy)

	- `policy` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the base64-encoded ACL policy.
	This is required unless the `token_type` is `"management"`. [Deprecated from Consul as of 1.4 and
	removed as of Consul 1.11.](/consul/api-docs/acl/legacy)

	- `policies` <sup>DEPRECATED (1.11)</sup> `(list: <policy or policies>)` - Same as `consul_policies`.
	Deprecated in favor of using `consul_policies`.

	- `consul_policies` `(list: <policy or policies>)` – The list of Consul policies to assign
	to the generated token. This field is required if using using Consul 1.4.

	- `local` `(bool: false)` - Indicates that the token should not be replicated
	globally and instead be local to the current datacenter. Only available in Consul
	1.4 and greater.

	- `ttl` `(duration: "")` – Specifies the TTL for this role. If not
	provided, the default Vault TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format).

	- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not
	provided, the default Vault Max TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format).

	### Sample payload

	To create a client token with policies defined in Consul:

	```json
	{
	"consul_policies": "policy-1,policy-2"
	}
	```

	### Parameters for consul version below 1.4

	- `lease` <sup>DEPRECATED (1.11)</sup> `(string: "")` – Specifies the lease for this role.
	Uses [duration format strings](/vault/docs/concepts/duration-format). If not
	provided, the default Vault lease is used.

	- `policy` <sup>DEPRECATED (1.11)</sup> `(string: <policy>)` – Specifies the base64-encoded ACL policy. The
	ACL format can be found in the [Consul ACL
	documentation](/consul/docs/security/acl/acl-legacy). This is
	required unless the `token_type` is `"management"`.

	### Sample payload

	To create a client token with a base64-encoded policy:

	```json
	{
	"policy": "a2V5ICIi...=="
	}
	```

	To create management tokens:

	```json
	{
	"token_type": "management"
	}
	```

	### Sample request

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

	## Read role

	This endpoint queries for information about a Consul role with the given name.
	If no role exists with that name, a 404 is returned.

	\| Method \| Path \|
	\| :----- \| :-------------------- \|
	\| `GET` \| `/consul/roles/:name` \|

	### Parameters

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

	### Sample request

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

	### Sample response

	```json
	{
	"data": {
	"policy": "abd2...==",
	"lease": "1h0m0s",
	"token_type": "client"
	}
	}
	```

	## List roles

	This endpoint lists all existing roles in the secrets engine.

	\| Method \| Path \|
	\| :----- \| :-------------- \|
	\| `LIST` \| `/consul/roles` \|

	### Sample request

	```shell-session
	$ curl \
	--header "X-Vault-Token: ..." \
	--request LIST \
	http://127.0.0.1:8200/v1/consul/roles
	```

	### Sample response

	```json
	{
	"data": {
	"keys": ["example-role"]
	}
	}
	```

	## Delete role

	This endpoint deletes a Consul role with the given name. Even if the role does
	not exist, this endpoint will still return a successful response.

	\| Method \| Path \|
	\| :------- \| :-------------------- \|
	\| `DELETE` \| `/consul/roles/:name` \|

	### Parameters

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

	### Sample request

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

	## Generate credential

	This endpoint generates a dynamic Consul token based on the given role
	definition.

	\| Method \| Path \|
	\| :----- \| :-------------------- \|
	\| `GET` \| `/consul/creds/:name` \|

	### Parameters

	- `name` `(string: <required>)` – Specifies the name of an existing role against
	which to create this Consul credential. This is part of the request URL.

	### Sample request

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

	### Sample response

	```json
	{
	"data": {
	"token": "973a31ea-1ec4-c2de-0f63-623f477c2510"
	}
	}
	```