ACL Policy HTTP API

The /acl/policy endpoints create, read, update, list and delete ACL policies in Consul.

For more information on how to setup ACLs, please check the ACL tutorial.

Create a Policy

This endpoint creates a new ACL policy.

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

The corresponding CLI command is consul acl policy create.

Parameters

• Name (string: <required>) - Specifies a name for the ACL policy. The name can contain alphanumeric characters, dashes -, and underscores _. This name must be unique.

• Description (string: "") - Free form human readable description of the policy.

• Rules (string: "") - Specifies rules for the ACL policy. The format of the Rules property is detailed in the ACL Rules documentation.

• Datacenters (array<string>) - Specifies the datacenters the policy is valid within. When no datacenters are provided the policy is valid in all datacenters including those which do not yet exist but may in the future.

• Namespace (string: "") EnterpriseEnterprise - Specifies the namespace to create the policy. If not provided in the JSON body, the value of the ns URL query parameter or in the X-Consul-Namespace header will be used. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Payload

{
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"]
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/policy

Sample Response

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

Read a Policy

This endpoint reads an ACL policy with the given ID.

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

The corresponding CLI command is consul acl policy read.

Parameters

• id (string: <required>) - Specifies the UUID of the ACL policy to read. This is required and is specified as part of the URL path.

• ns (string: "") EnterpriseEnterprise - Specifies the namespace to lookup the policy. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9fdc78f5

Sample Response

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

Read a Policy by Name

This endpoint reads an ACL policy with the given ID.

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

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

Parameters

• name (string: <required>) - Specifies the name of the ACL policy to read. This is required and is specified as part of the URL path.

• ns (string: "") EnterpriseEnterprise - Specifies the namespace to lookup the policy. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/name/node-read

Sample Response

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

Update a Policy

This endpoint updates an existing ACL policy.

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

The corresponding CLI command is consul acl policy update.

Parameters

• ID (string: <required>) - Specifies the UUID of the policy to update. This is required in the URL path but may also be specified in the JSON body. If specified in both places then they must match exactly.

• Name (string: <required>) - Specifies a name for the ACL policy. The name can only contain alphanumeric characters as well as - and _ and must be unique.

• Description (string: "") - Free form human readable description of this policy.

• Rules (string: "") - Specifies rules for this ACL policy. The format of the Rules property is detailed in the ACL Rules documentation.

• Datacenters (array<string>) - Specifies the datacenters this policy is valid within. When no datacenters are provided the policy is valid in all datacenters including those which do not yet exist but may in the future.

• Namespace (string: "") EnterpriseEnterprise - Specifies the namespace of the policy to update. If not provided in the JSON body, the value of the ns URL query parameter or in the X-Consul-Namespace header will be used. If not provided, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Payload

{
  "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
  "Name": "register-app-service",
  "Description": "Grants write permissions necessary to register the 'app' service",
  "Rules": "service \"app\" { policy = \"write\"}"
}

Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/policy/c01a1f82-44be-41b0-a686-685fb6e0f485

Sample Response

{
  "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
  "Name": "register-app-service",
  "Description": "Grants write permissions necessary to register the 'app' service",
  "Rules": "service \"app\" { policy = \"write\"}",
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 28
}

Delete a Policy

This endpoint deletes an ACL policy.

Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded.

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

The corresponding CLI command is consul acl policy delete.

Parameters

• id (string: <required>) - Specifies the UUID of the ACL policy to delete. This is required and is specified as part of the URL path.

• ns (string: "") EnterpriseEnterprise - Specifies the namespace of the policy to delete. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. Added in Consul 1.7.0.

Sample Request

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/policy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

Sample Response

true

List Policies

This endpoint lists all the ACL policies.

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

The corresponding CLI command is consul acl policy list.

Parameters

• ns (string: "") EnterpriseEnterprise - Specifies the namespace to list the Policies for. This value can be specified as the ns URL query parameter or the X-Consul-Namespace header. If not provided by either, the namespace will be inherited from the request's ACL token or will default to the default namespace. The namespace may be specified as '*' and then results will be returned for all namespaces. Added in Consul 1.7.0.

Sample Request

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

Sample Response

[
  {
    "CreateIndex": 4,
    "Datacenters": null,
    "Description": "Builtin Policy that grants unlimited access",
    "Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=",
    "ID": "00000000-0000-0000-0000-000000000001",
    "ModifyIndex": 4,
    "Name": "global-management"
  },
  {
    "CreateIndex": 14,
    "Datacenters": ["dc1"],
    "Description": "Grants read access to all node information",
    "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
    "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
    "ModifyIndex": 14,
    "Name": "node-read"
  }
]