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