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