ACL Templated Policy HTTP API

The /acl/templated-policy endpoints read, preview, and list ACL templated policies in Consul.

For more information on how to setup ACLs, refer to the following resources:

Read a templated policy by name

This endpoint reads an ACL policy with the given ID.

Method	Path	Produces
`GET`	`/acl/templated-policy/name/:name`	`application/json`

The following table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:read`

The corresponding CLI command is consul acl templated-policy read -name=<string>.

Path parameters

name (string: <required>) - Specifies the name of the ACL policy to read.

Sample request

$ curl --request GET http://127.0.0.1:8500/v1/acl/templated-policy/name/builtin/service

Sample response

{
  "TemplateName": "builtin/service",
  "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
  "Template": "\nservice \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice \"{{.Name}}-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}"
}

Preview a templated policy

The preview endpoint shows the policy created from a templated policy. The endpoint helps you understand what templated variables are required or are missing from your request.

Method	Path	Produces
`POST`	`/acl/templated-policy/preview/:name`	`application/json`

The following table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:read`

The corresponding CLI command is consul acl templated-policy preview.

Path parameters

name (string: <required>) - Specifies the name of the ACL templated policy to preview.

Query parameters

ns (string: "") Enterprise - Specifies the namespace that the policy created from the template applies to. You can also specify the namespace through other methods.

JSON request body schema

Name (string: <optional>) - Specifies the value of the name variable in the templated policy variables.

Partition (string: "") - Enterprise The admin partition to use. If not provided, the partition is inferred from the request's ACL token, or defaults to the default partition.

Sample payload

{
  "Name": "api"
}

Sample request

$ curl --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl-templated/preview/builtin/service

Sample response

{
    "ID": "0a73657276696365202277656222207...",
    "Name": "synthetic-policy-0a73657276...",
    "Description": "synthetic policy generated from templated policy: builtin/service",
    "Rules": "\nservice \"web\" {\n\tpolicy = \"write\"\n}\nservice \"web-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}",
    "Hash": "b04MnvCVtBXZAmGe4uDpGLABJoGo2nNhEJkqaN5E5x4=",
    "CreateIndex": 0,
    "ModifyIndex": 0
}

List templated policies

Call the templated-policies endpoint with a GET method to list all templated ACL policies.

Method	Path	Produces
`GET`	`/acl/templated-policies`	`application/json`

The following table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`No`	`none`	`none`	`acl:read`

The corresponding CLI command is consul acl templated-policy list.

Query parameters

This endpoint does not accept query parameters.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/templated-policies

Sample response

{
  "builtin/dns": {
      "TemplateName": "builtin/dns",
      "Schema": "",
      "Template": "\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nquery_prefix \"\" {\n\tpolicy = \"read\"\n}"
  },
  "builtin/node": {
      "TemplateName": "builtin/node",
      "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
      "Template": "\nnode \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}"
  },
  "builtin/nomad-server": {
      "TemplateName": "builtin/nomad-server",
      "Schema": "",
      "Template": "\nacl = \"write\"\nagent_prefix \"\" {\n  policy = \"read\"\n}\nnode_prefix \"\" {\n  policy = \"read\"\n}\nservice_prefix \"\" {\n  policy = \"write\"\n}"
  },
  "builtin/service": {
      "TemplateName": "builtin/service",
      "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
      "Template": "\nservice \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice \"{{.Name}}-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}"
  },
  "builtin/workload-identity": {
      "TemplateName": "builtin/workload-identity",
      "Schema": "{\n  \"type\": \"object\",\n  \"properties\": {\n    \"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n  },\n  \"required\": [\"name\"],\n  \"definitions\": {\n    \"min-length-one\": {\n      \"type\": \"string\",\n      \"minLength\": 1\n    }\n  }\n}",
      "Template": "identity \"{{.Name}}\" {\n\tpolicy = \"write\"\n}"
  }
}

Methods to specify namespace Enterprise

You can employ several methods to specify the namespace in calls to templated ACL policy endpoints. Consul applies the following order of precedence to determine the namespace:

Namespace field of the JSON request body. This method only applies to create and update endpoints
ns query parameter.
X-Consul-Namespace request header.
Namespace inherited from the namespace of the request's ACL token.
The default namespace.

ACL Templated Policy HTTP API

Read a templated policy by name

Path parameters

Sample request

Sample response

Preview a templated policy

Path parameters

Query parameters

JSON request body schema

Sample payload

Sample request

Sample response

List templated policies

Query parameters

Sample Request

Sample response

Methods to specify namespace EnterpriseEnterprise

Methods to specify namespace Enterprise