1--- 2layout: api 3page_title: ACL Policies - HTTP API 4sidebar_current: api-acl-policies 5description: |- 6 The /acl/policy endpoints manage Consul's ACL policies. 7--- 8 9-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api/acl/legacy.html) 10 11# ACL Policy HTTP API 12 13The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy), 14[update](#update-a-policy), [list](#list-policies) and 15[delete](#delete-a-policy) ACL policies in Consul. 16 17For more information on how to setup ACLs, please see 18the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls). 19 20## Create a Policy 21 22This endpoint creates a new ACL policy. 23 24| Method | Path | Produces | 25| ------ | ---------------------------- | -------------------------- | 26| `PUT` | `/acl/policy` | `application/json` | 27 28The table below shows this endpoint's support for 29[blocking queries](/api/features/blocking.html), 30[consistency modes](/api/features/consistency.html), 31[agent caching](/api/features/caching.html), and 32[required ACLs](/api/index.html#authentication). 33 34| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 35| ---------------- | ----------------- | ------------- | ------------ | 36| `NO` | `none` | `none` | `acl:write` | 37 38### Parameters 39 40- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name 41 can contain alphanumeric characters, dashes `-`, and underscores `_`. 42 This name must be unique. 43 44- `Description` `(string: "")` - Free form human readable description of the policy. 45 46- `Rules` `(string: "")` - Specifies rules for the ACL policy. The format of the 47 `Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html). 48 49- `Datacenters` `(array<string>)` - Specifies the datacenters the policy is valid within. 50 When no datacenters are provided the policy is valid in all datacenters including 51 those which do not yet exist but may in the future. 52 53- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to 54 create the policy. If not provided in the JSON body, the value of 55 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 56 If not provided at all, the namespace will be inherited from the request's ACL 57 token or will default to the `default` namespace. Added in Consul 1.7.0. 58 59### Sample Payload 60 61```json 62{ 63 "Name": "node-read", 64 "Description": "Grants read access to all node information", 65 "Rules": "node_prefix \"\" { policy = \"read\"}", 66 "Datacenters": ["dc1"] 67} 68``` 69 70### Sample Request 71 72```sh 73$ curl -X PUT \ 74 --data @payload.json \ 75 http://127.0.0.1:8500/v1/acl/policy 76``` 77 78### Sample Response 79 80```json 81{ 82 "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", 83 "Name": "node-read", 84 "Description": "Grants read access to all node information", 85 "Rules": "node_prefix \"\" { policy = \"read\"}", 86 "Datacenters": [ 87 "dc1" 88 ], 89 "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", 90 "CreateIndex": 14, 91 "ModifyIndex": 14 92} 93 94``` 95 96## Read a Policy 97 98This endpoint reads an ACL policy with the given ID. 99 100| Method | Path | Produces | 101| ------ | ---------------------------- | -------------------------- | 102| `GET` | `/acl/policy/:id` | `application/json` | 103 104The table below shows this endpoint's support for 105[blocking queries](/api/features/blocking.html), 106[consistency modes](/api/features/consistency.html), 107[agent caching](/api/features/caching.html), and 108[required ACLs](/api/index.html#authentication). 109 110| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 111| ---------------- | ----------------- | ------------- | ------------ | 112| `YES` | `all` | `none` | `acl:read` | 113 114### Parameters 115 116- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to 117 read. This is required and is specified as part of the URL path. 118 119- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup 120 the policy. This value can be specified as the `ns` URL query 121 parameter or the `X-Consul-Namespace` header. If not provided by either, 122 the namespace will be inherited from the request's ACL token or will default 123 to the `default` namespace. Added in Consul 1.7.0. 124 125### Sample Request 126 127```sh 128$ curl -X GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9fdc78f5 129``` 130 131### Sample Response 132 133```json 134{ 135 "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", 136 "Name": "node-read", 137 "Description": "Grants read access to all node information", 138 "Rules": "node_prefix \"\" { policy = \"read\"}", 139 "Datacenters": [ 140 "dc1" 141 ], 142 "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", 143 "CreateIndex": 14, 144 "ModifyIndex": 14 145} 146``` 147 148## Update a Policy 149 150This endpoint updates an existing ACL policy. 151 152| Method | Path | Produces | 153| ------ | ---------------------------- | -------------------------- | 154| `PUT` | `/acl/policy/:id` | `application/json` | 155 156The table below shows this endpoint's support for 157[blocking queries](/api/features/blocking.html), 158[consistency modes](/api/features/consistency.html), 159[agent caching](/api/features/caching.html), and 160[required ACLs](/api/index.html#authentication). 161 162| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 163| ---------------- | ----------------- | ------------- | ------------ | 164| `NO` | `none` | `none` | `acl:write` | 165 166### Parameters 167 168- `ID` `(string: <required>)` - Specifies the UUID of the policy to update. This is 169 required in the URL path but may also be specified in the JSON body. If specified 170 in both places then they must match exactly. 171 172- `Name` `(string: <required>)` - Specifies a name for the ACL policy. The name 173 can only contain alphanumeric characters as well as `-` and `_` and must be 174 unique. 175 176- `Description` `(string: "")` - Free form human readable description of this policy. 177 178- `Rules` `(string: "")` - Specifies rules for this ACL policy. The format of the 179 `Rules` property is detailed in the [ACL Rules documentation](/docs/acl/acl-rules.html). 180 181- `Datacenters` `(array<string>)` - Specifies the datacenters this policy is valid within. 182 When no datacenters are provided the policy is valid in all datacenters including 183 those which do not yet exist but may in the future. 184 185- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of 186 the policy to update. If not provided in the JSON body, the value of 187 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 188 If not provided at all, the namespace will be inherited from the request's ACL 189 token or will default to the `default` namespace. Added in Consul 1.7.0. 190 191### Sample Payload 192 193```json 194{ 195 "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485", 196 "Name": "register-app-service", 197 "Description": "Grants write permissions necessary to register the 'app' service", 198 "Rules": "service \"app\" { policy = \"write\"}", 199} 200``` 201 202### Sample Request 203 204```sh 205$ curl -X PUT \ 206 --data @payload.json \ 207 http://127.0.0.1:8500/v1/acl/policy/c01a1f82-44be-41b0-a686-685fb6e0f485 208``` 209 210### Sample Response 211 212```json 213{ 214 "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485", 215 "Name": "register-app-service", 216 "Description": "Grants write permissions necessary to register the 'app' service", 217 "Rules": "service \"app\" { policy = \"write\"}", 218 "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", 219 "CreateIndex": 14, 220 "ModifyIndex": 28 221} 222``` 223 224## Delete a Policy 225 226This endpoint deletes an ACL policy. 227 228| Method | Path | Produces | 229| -------- | ------------------------- | -------------------------- | 230| `DELETE` | `/acl/policy/:id` | `application/json` | 231 232Even though the return type is application/json, the value is either true or 233false indicating whether the delete succeeded. 234 235The table below shows this endpoint's support for 236[blocking queries](/api/features/blocking.html), 237[consistency modes](/api/features/consistency.html), 238[agent caching](/api/features/caching.html), and 239[required ACLs](/api/index.html#authentication). 240 241| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 242| ---------------- | ----------------- | ------------- | ------------ | 243| `NO` | `none` | `none` | `acl:write` | 244 245### Parameters 246 247- `id` `(string: <required>)` - Specifies the UUID of the ACL policy to 248 delete. This is required and is specified as part of the URL path. 249 250- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the 251 policy to delete. This value can be specified as the `ns` URL query 252 parameter or the `X-Consul-Namespace` header. If not provided by either, 253 the namespace will be inherited from the request's ACL token or will default 254 to the `default` namespace. Added in Consul 1.7.0. 255 256### Sample Request 257 258```sh 259$ curl -X DELETE \ 260 http://127.0.0.1:8500/v1/acl/policy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 261``` 262 263### Sample Response 264```json 265true 266``` 267 268## List Policies 269 270This endpoint lists all the ACL policies. 271 272| Method | Path | Produces | 273| ------ | ---------------------------- | -------------------------- | 274| `GET` | `/acl/policies` | `application/json` | 275 276The table below shows this endpoint's support for 277[blocking queries](/api/features/blocking.html), 278[consistency modes](/api/features/consistency.html), 279[agent caching](/api/features/caching.html), and 280[required ACLs](/api/index.html#authentication). 281 282| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 283| ---------------- | ----------------- | ------------- | ------------ | 284| `YES` | `all` | `none` | `acl:read` | 285 286### Parameters 287 288- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list 289 the Policies for. This value can be specified as the `ns` URL query 290 parameter or the `X-Consul-Namespace` header. If not provided by either, 291 the namespace will be inherited from the request's ACL token or will default 292 to the `default` namespace. The namespace may be specified as '*' and then 293 results will be returned for all namespaces. Added in Consul 1.7.0. 294 295## Sample Request 296 297```sh 298$ curl -X GET http://127.0.0.1:8500/v1/acl/policies 299``` 300 301### Sample Response 302 303-> **Note** - The policies rules are not included in the listing and must be 304 retrieved by the [policy reading endpoint](#read-a-policy) 305 306```json 307[ 308 { 309 "CreateIndex": 4, 310 "Datacenters": null, 311 "Description": "Builtin Policy that grants unlimited access", 312 "Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=", 313 "ID": "00000000-0000-0000-0000-000000000001", 314 "ModifyIndex": 4, 315 "Name": "global-management" 316 }, 317 { 318 "CreateIndex": 14, 319 "Datacenters": [ 320 "dc1" 321 ], 322 "Description": "Grants read access to all node information", 323 "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=", 324 "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5", 325 "ModifyIndex": 14, 326 "Name": "node-read" 327 } 328] 329 330``` 331