github.com/outbrain/consul@v1.4.5/website/source/api/acl/legacy.html.md (about) 1 --- 2 layout: api 3 page_title: Legacy ACLs - HTTP API 4 sidebar_current: api-acl-tokens-legacy 5 description: |- 6 The /acl endpoints create, update, destroy, and query Legacy ACL tokens in Consul. 7 --- 8 9 -> **Consul 1.4.0 deprecates the legacy ACL system completely.** It's _strongly_ 10 recommended you do not build anything using the legacy system and consider using 11 the new ACL [Token](/api/acl/tokens.html) and [Policy](/api/acl/policies.html) APIs instead. 12 13 # ACL HTTP API 14 15 The `/acl` endpoints create, update, destroy, and query ACL tokens in Consul. For more information about ACLs, please see the [ACL Guide](/docs/guides/acl-legacy.html). 16 17 ## Create ACL Token 18 19 This endpoint makes a new ACL token. 20 21 | Method | Path | Produces | 22 | ------ | ---------------------------- | -------------------------- | 23 | `PUT` | `/acl/create` | `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` | `management` | 34 35 ### Parameters 36 37 - `ID` `(string: "")` - Specifies the ID of the ACL. If not provided, a UUID is 38 generated. 39 40 - `Name` `(string: "")` - Specifies a human-friendly name for the ACL token. 41 42 - `Type` `(string: "client")` - Specifies the type of ACL token. Valid values 43 are: `client` and `management`. 44 45 - `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the 46 `Rules` property is documented in the [ACL Guide](/docs/guides/acl-legacy.html). 47 48 ### Sample Payload 49 50 ```json 51 { 52 "Name": "my-app-token", 53 "Type": "client", 54 "Rules": "" 55 } 56 ``` 57 58 ### Sample Request 59 60 ```text 61 $ curl \ 62 --request PUT \ 63 --data @payload.json \ 64 http://127.0.0.1:8500/v1/acl/create 65 ``` 66 67 ### Sample Response 68 69 ```json 70 { 71 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 72 } 73 ``` 74 75 ## Update ACL Token 76 77 This endpoint is used to modify the policy for a given ACL token. Instead of 78 generating a new token ID, the `ID` field must be provided. 79 80 | Method | Path | Produces | 81 | ------ | ---------------------------- | -------------------------- | 82 | `PUT` | `/acl/update` | `application/json` | 83 84 The table below shows this endpoint's support for 85 [blocking queries](/api/index.html#blocking-queries), 86 [consistency modes](/api/index.html#consistency-modes), 87 [agent caching](/api/index.html#agent-caching), and 88 [required ACLs](/api/index.html#acls). 89 90 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 91 | ---------------- | ----------------- | ------------- | ------------ | 92 | `NO` | `none` | `none` | `management` | 93 94 ### Parameters 95 96 The parameters are the same as the _create_ endpoint, except the `ID` field is 97 required. 98 99 ### Sample Payload 100 101 ```json 102 { 103 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e", 104 "Name": "my-app-token-updated", 105 "Type": "client", 106 "Rules": "# New Rules", 107 } 108 ``` 109 110 ### Sample Request 111 112 ```text 113 $ curl \ 114 --request PUT \ 115 --data @payload.json \ 116 http://127.0.0.1:8500/v1/acl/update 117 ``` 118 119 ### Sample Response 120 ```json 121 { 122 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 123 } 124 ``` 125 126 127 ## Delete ACL Token 128 129 This endpoint deletes an ACL token with the given ID. 130 131 | Method | Path | Produces | 132 | ------ | ---------------------------- | -------------------------- | 133 | `PUT` | `/acl/destroy/:uuid` | `application/json` | 134 135 Even though the return type is application/json, the value is either true or 136 false, indicating whether the delete succeeded. 137 138 The table below shows this endpoint's support for 139 [blocking queries](/api/index.html#blocking-queries), 140 [consistency modes](/api/index.html#consistency-modes), 141 [agent caching](/api/index.html#agent-caching), and 142 [required ACLs](/api/index.html#acls). 143 144 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 145 | ---------------- | ----------------- | ------------- | ------------ | 146 | `NO` | `none` | `none` | `management` | 147 148 ### Parameters 149 150 - `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to 151 destroy. This is required and is specified as part of the URL path. 152 153 ### Sample Request 154 155 ```text 156 $ curl \ 157 --request PUT \ 158 http://127.0.0.1:8500/v1/acl/destroy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 159 ``` 160 161 ### Sample Response 162 ```json 163 true 164 ``` 165 166 ## Read ACL Token 167 168 This endpoint reads an ACL token with the given ID. 169 170 | Method | Path | Produces | 171 | ------ | ---------------------------- | -------------------------- | 172 | `GET` | `/acl/info/:uuid` | `application/json` | 173 174 The table below shows this endpoint's support for 175 [blocking queries](/api/index.html#blocking-queries), 176 [consistency modes](/api/index.html#consistency-modes), 177 [agent caching](/api/index.html#agent-caching), and 178 [required ACLs](/api/index.html#acls). 179 180 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 181 | ---------------- | ----------------- | ------------- | ------------ | 182 | `YES` | `all` | `none` | `none` | 183 184 Note: No ACL is required because the ACL is specified in the URL path. 185 186 ### Parameters 187 188 - `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to 189 read. This is required and is specified as part of the URL path. 190 191 ### Sample Request 192 193 ```text 194 $ curl \ 195 http://127.0.0.1:8500/v1/acl/info/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 196 ``` 197 198 ### Sample Response 199 200 ```json 201 [ 202 { 203 "CreateIndex": 3, 204 "ModifyIndex": 3, 205 "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05", 206 "Name": "Client Token", 207 "Type": "client", 208 "Rules": "..." 209 } 210 ] 211 ``` 212 213 ## Clone ACL Token 214 215 This endpoint clones an ACL and returns a new token `ID`. This allows a token to 216 serve as a template for others, making it simple to generate new tokens without 217 complex rule management. 218 219 | Method | Path | Produces | 220 | ------ | ---------------------------- | -------------------------- | 221 | `PUT` | `/acl/clone/:uuid` | `application/json` | 222 223 The table below shows this endpoint's support for 224 [blocking queries](/api/index.html#blocking-queries), 225 [consistency modes](/api/index.html#consistency-modes), 226 [agent caching](/api/index.html#agent-caching), and 227 [required ACLs](/api/index.html#acls). 228 229 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 230 | ---------------- | ----------------- | ------------- | ------------ | 231 | `NO` | `none` | `none` | `management` | 232 233 ### Parameters 234 235 - `uuid` `(string: <required>)` - Specifies the UUID of the ACL token to 236 be cloned. This is required and is specified as part of the URL path. 237 238 ### Sample Request 239 240 ```text 241 $ curl \ 242 --request PUT \ 243 http://127.0.0.1:8500/v1/acl/clone/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 244 ``` 245 246 ### Sample Response 247 248 ```json 249 { 250 "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e" 251 } 252 ``` 253 254 ## List ACLs 255 256 This endpoint lists all the active ACL tokens. 257 258 | Method | Path | Produces | 259 | ------ | ---------------------------- | -------------------------- | 260 | `GET` | `/acl/list` | `application/json` | 261 262 The table below shows this endpoint's support for 263 [blocking queries](/api/index.html#blocking-queries), 264 [consistency modes](/api/index.html#consistency-modes), 265 [agent caching](/api/index.html#agent-caching), and 266 [required ACLs](/api/index.html#acls). 267 268 | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 269 | ---------------- | ----------------- | ------------- | ------------ | 270 | `YES` | `all` | `none` | `management` | 271 272 ### Sample Request 273 274 ```text 275 $ curl \ 276 http://127.0.0.1:8500/v1/acl/list 277 ``` 278 279 ### Sample Response 280 281 ```json 282 [ 283 { 284 "CreateIndex": 3, 285 "ModifyIndex": 3, 286 "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05", 287 "Name": "Client Token", 288 "Type": "client", 289 "Rules": "..." 290 } 291 ] 292 ```