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