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