1---
2layout: api
3page_title: ACL Roles - HTTP API
4sidebar_current: api-acl-roles
5description: |-
6  The /acl/role endpoints manage Consul's ACL Roles.
7---
8
9-> **1.5.0+:**  The role APIs are available in Consul versions 1.5.0 and newer.
10
11# ACL Role HTTP API
12
13The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
14[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role)  ACL roles in Consul.
15
16For more information on how to setup ACLs, please see
17the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls).
18
19## Create a Role
20
21This endpoint creates a new ACL role.
22
23| Method | Path                         | Produces                   |
24| ------ | ---------------------------- | -------------------------- |
25| `PUT`  | `/acl/role`                  | `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`        | `acl:write`  |
36
37### Parameters
38
39- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
40  can contain alphanumeric characters, dashes `-`, and  underscores `_`.
41  This name must be unique.
42
43- `Description` `(string: "")` - Free form human readable description of the role.
44
45- `Policies` `(array<PolicyLink>)` - The list of policies that should be
46  applied to the role. A PolicyLink is an object with an "ID" and/or "Name"
47  field to specify a policy. With the PolicyLink, roles can be linked to
48  policies either by the policy name or by the policy ID. When policies are
49  linked by name they will be internally resolved to the policy ID. With
50  linking roles internally by IDs, Consul enables policy renaming without
51  breaking tokens.
52
53- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
54  identities](/docs/acl/acl-system.html#acl-service-identities) that should be
55  applied to the role.  Added in Consul 1.5.0.
56
57  - `ServiceName` `(string: <required>)` - The name of the service. The name
58    must be no longer than 256 characters, must start and end with a lowercase
59    alphanumeric character, and can only contain lowercase alphanumeric
60    characters as well as `-` and `_`.
61
62  - `Datacenters` `(array<string>)` - Specifies the datacenters the effective
63    policy is valid within. When no datacenters are provided the effective
64    policy is valid in all datacenters including those which do not yet exist
65    but may in the future.
66
67- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to
68  create the role. If not provided in the JSON body, the value of
69  the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
70  If not provided at all, the namespace will be inherited from the request's ACL
71  token or will default to the `default` namespace. Added in Consul 1.7.0.
72
73### Sample Payload
74
75```json
76{
77    "Name": "example-role",
78    "Description": "Showcases all input parameters",
79    "Policies": [
80        {
81            "ID": "783beef3-783f-f41f-7422-7087dc272765"
82        },
83        {
84            "Name": "node-read"
85        }
86    ],
87    "ServiceIdentities": [
88        {
89            "ServiceName": "web"
90        },
91        {
92            "ServiceName": "db",
93            "Datacenters": [
94                "dc1"
95            ]
96        }
97    ]
98}
99```
100
101### Sample Request
102
103```sh
104$ curl -X PUT \
105    --data @payload.json \
106    http://127.0.0.1:8500/v1/acl/role
107```
108
109### Sample Response
110
111```json
112{
113    "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
114    "Name": "example-role",
115    "Description": "Showcases all input parameters",
116    "Policies": [
117        {
118            "ID": "783beef3-783f-f41f-7422-7087dc272765",
119            "Name": "node-read"
120        }
121    ],
122    "ServiceIdentities": [
123        {
124            "ServiceName": "web"
125        },
126        {
127            "ServiceName": "db",
128            "Datacenters": [
129                "dc1"
130            ]
131        }
132    ],
133    "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
134    "CreateIndex": 57,
135    "ModifyIndex": 57
136}
137```
138
139## Read a Role
140
141This endpoint reads an ACL role with the given ID. If no role exists with the
142given ID, a 404 is returned instead of a 200 response.
143
144| Method | Path                         | Produces                   |
145| ------ | ---------------------------- | -------------------------- |
146| `GET`  | `/acl/role/:id`              | `application/json`         |
147
148The table below shows this endpoint's support for
149[blocking queries](/api/features/blocking.html),
150[consistency modes](/api/features/consistency.html),
151[agent caching](/api/features/caching.html), and
152[required ACLs](/api/index.html#authentication).
153
154| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
155| ---------------- | ----------------- | ------------- | ------------ |
156| `YES`            | `all`             | `none`        | `acl:read`   |
157
158### Parameters
159
160- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
161   read. This is required and is specified as part of the URL path.
162
163- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
164  the role. This value can be specified as the `ns` URL query
165  parameter or the `X-Consul-Namespace` header. If not provided by either,
166  the namespace will be inherited from the request's ACL token or will default
167  to the `default` namespace. Added in Consul 1.7.0.
168
169### Sample Request
170
171```sh
172$ curl -X GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4
173```
174
175### Sample Response
176
177```json
178{
179    "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
180    "Name": "example-role",
181    "Description": "Showcases all input parameters",
182    "Policies": [
183        {
184            "ID": "783beef3-783f-f41f-7422-7087dc272765",
185            "Name": "node-read"
186        }
187    ],
188    "ServiceIdentities": [
189        {
190            "ServiceName": "web"
191        },
192        {
193            "ServiceName": "db",
194            "Datacenters": [
195                "dc1"
196            ]
197        }
198    ],
199    "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
200    "CreateIndex": 57,
201    "ModifyIndex": 57
202}
203```
204
205## Read a Role by Name
206
207This endpoint reads an ACL role with the given name. If no role exists with the
208given name, a 404 is returned instead of a 200 response.
209
210| Method | Path                         | Produces                   |
211| ------ | ---------------------------- | -------------------------- |
212| `GET`  | `/acl/role/name/:name`       | `application/json`         |
213
214The table below shows this endpoint's support for
215[blocking queries](/api/features/blocking.html),
216[consistency modes](/api/features/consistency.html),
217[agent caching](/api/features/caching.html), and
218[required ACLs](/api/index.html#authentication).
219
220| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
221| ---------------- | ----------------- | ------------- | ------------ |
222| `YES`            | `all`             | `none`        | `acl:read`   |
223
224### Parameters
225
226- `name` `(string: <required>)` - Specifies the Name of the ACL role to
227   read. This is required and is specified as part of the URL path.
228
229- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup
230  the role. This value can be specified as the `ns` URL query
231  parameter or the `X-Consul-Namespace` header. If not provided by either,
232  the namespace will be inherited from the request's ACL token or will default
233  to the `default` namespace. Added in Consul 1.7.0.
234
235### Sample Request
236
237```sh
238$ curl -X GET http://127.0.0.1:8500/v1/acl/role/name/example-role
239```
240
241### Sample Response
242
243```json
244{
245    "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
246    "Name": "example-role",
247    "Description": "Showcases all input parameters",
248    "Policies": [
249        {
250            "ID": "783beef3-783f-f41f-7422-7087dc272765",
251            "Name": "node-read"
252        }
253    ],
254    "ServiceIdentities": [
255        {
256            "ServiceName": "web"
257        },
258        {
259            "ServiceName": "db",
260            "Datacenters": [
261                "dc1"
262            ]
263        }
264    ],
265    "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
266    "CreateIndex": 57,
267    "ModifyIndex": 57
268}
269```
270
271## Update a Role
272
273This endpoint updates an existing ACL role.
274
275| Method | Path                         | Produces                   |
276| ------ | ---------------------------- | -------------------------- |
277| `PUT`  | `/acl/role/:id`              | `application/json`         |
278
279The table below shows this endpoint's support for
280[blocking queries](/api/features/blocking.html),
281[consistency modes](/api/features/consistency.html),
282[agent caching](/api/features/caching.html), and
283[required ACLs](/api/index.html#authentication).
284
285| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
286| ---------------- | ----------------- | ------------- | ------------ |
287| `NO`             | `none`            | `none`        | `acl:write`  |
288
289### Parameters
290
291- `ID` `(string: <required>)` - Specifies the ID of the role to update. This is
292   required in the URL path but may also be specified in the JSON body. If specified
293   in both places then they must match exactly.
294
295- `Name` `(string: <required>)` - Specifies a name for the ACL role. The name
296  can only contain alphanumeric characters as well as `-` and `_` and must be
297  unique.
298
299- `Description` `(string: "")` - Free form human readable description of the role.
300
301- `Policies` `(array<PolicyLink>)` - The list of policies that should be
302  applied to the role. A PolicyLink is an object with an "ID" and/or "Name"
303  field to specify a policy. With the PolicyLink, roles can be linked to
304  policies either by the policy name or by the policy ID. When policies are
305  linked by name they will be internally resolved to the policy ID. With
306  linking roles internally by IDs, Consul enables policy renaming without
307  breaking tokens.
308
309- `ServiceIdentities` `(array<ServiceIdentity>)` - The list of [service
310  identities](/docs/acl/acl-system.html#acl-service-identities) that should be
311  applied to the role.  Added in Consul 1.5.0.
312
313- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of
314  the role to update. If not provided in the JSON body, the value of
315  the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used.
316  If not provided at all, the namespace will be inherited from the request's ACL
317  token or will default to the `default` namespace. Added in Consul 1.7.0.
318
319### Sample Payload
320
321```json
322{
323    "ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
324    "Name": "example-two",
325    "Policies": [
326        {
327            "Name": "node-read"
328        }
329    ],
330    "ServiceIdentities": [
331        {
332            "ServiceName": "db"
333        }
334    ]
335}
336```
337
338### Sample Request
339
340```sh
341$ curl -X PUT \
342    --data @payload.json \
343    http://127.0.0.1:8500/v1/acl/role/8bec74a4-5ced-45ed-9c9d-bca6153490bb
344```
345
346### Sample Response
347
348```json
349{
350    "ID": "8bec74a4-5ced-45ed-9c9d-bca6153490bb",
351    "Name": "example-two",
352    "Policies": [
353        {
354            "ID": "783beef3-783f-f41f-7422-7087dc272765",
355            "Name": "node-read"
356        }
357    ],
358    "ServiceIdentities": [
359        {
360            "ServiceName": "db"
361        }
362    ],
363    "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
364    "CreateIndex": 14,
365    "ModifyIndex": 28
366}
367```
368
369## Delete a Role
370
371This endpoint deletes an ACL role.
372
373| Method   | Path                      | Produces                   |
374| -------- | ------------------------- | -------------------------- |
375| `DELETE` | `/acl/role/:id`           | `application/json`         |
376
377Even though the return type is application/json, the value is either true or
378false indicating whether the delete succeeded.
379
380The table below shows this endpoint's support for
381[blocking queries](/api/features/blocking.html),
382[consistency modes](/api/features/consistency.html),
383[agent caching](/api/features/caching.html), and
384[required ACLs](/api/index.html#authentication).
385
386| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
387| ---------------- | ----------------- | ------------- | ------------ |
388| `NO`             | `none`            | `none`        | `acl:write`  |
389
390### Parameters
391
392- `id` `(string: <required>)` - Specifies the UUID of the ACL role to
393  delete. This is required and is specified as part of the URL path.
394
395- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the
396  role to delete. This value can be specified as the `ns` URL query
397  parameter or the `X-Consul-Namespace` header. If not provided by either,
398  the namespace will be inherited from the request's ACL token or will default
399  to the `default` namespace. Added in Consul 1.7.0.
400
401### Sample Request
402
403```sh
404$ curl -X DELETE \
405    http://127.0.0.1:8500/v1/acl/role/8f246b77-f3e1-ff88-5b48-8ec93abf3e05
406```
407
408### Sample Response
409```json
410true
411```
412
413## List Roles
414
415This endpoint lists all the ACL roles.
416
417| Method | Path                         | Produces                   |
418| ------ | ---------------------------- | -------------------------- |
419| `GET`  | `/acl/roles`                 | `application/json`         |
420
421The table below shows this endpoint's support for
422[blocking queries](/api/features/blocking.html),
423[consistency modes](/api/features/consistency.html),
424[agent caching](/api/features/caching.html), and
425[required ACLs](/api/index.html#authentication).
426
427| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
428| ---------------- | ----------------- | ------------- | ------------ |
429| `YES`            | `all`             | `none`        | `acl:read`   |
430
431## Parameters
432
433- `policy` `(string: "")` - Filters the role list to those roles that are
434  linked with the specific policy ID.
435
436### Parameters
437
438- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list
439  the roles for. This value can be specified as the `ns` URL query
440  parameter or the `X-Consul-Namespace` header. If not provided by either,
441  the namespace will be inherited from the request's ACL token or will default
442  to the `default` namespace. The namespace may be specified as '*' and then
443  results will be returned for all namespaces. Added in Consul 1.7.0.
444
445## Sample Request
446
447```sh
448$ curl -X GET http://127.0.0.1:8500/v1/acl/roles
449```
450
451### Sample Response
452
453```json
454[
455    {
456        "ID": "5e52a099-4c90-c067-5478-980f06be9af5",
457        "Name": "node-read",
458        "Description": "",
459        "Policies": [
460            {
461                "ID": "783beef3-783f-f41f-7422-7087dc272765",
462                "Name": "node-read"
463            }
464        ],
465        "Hash": "K6AbfofgiZ1BEaKORBloZf7WPdg45J/PipHxQiBlK1U=",
466        "CreateIndex": 50,
467        "ModifyIndex": 50
468    },
469    {
470        "ID": "aa770e5b-8b0b-7fcf-e5a1-8535fcc388b4",
471        "Name": "example-role",
472        "Description": "Showcases all input parameters",
473        "Policies": [
474            {
475                "ID": "783beef3-783f-f41f-7422-7087dc272765",
476                "Name": "node-read"
477            }
478        ],
479        "ServiceIdentities": [
480            {
481                "ServiceName": "web"
482            },
483            {
484                "ServiceName": "db",
485                "Datacenters": [
486                    "dc1"
487                ]
488            }
489        ],
490        "Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
491        "CreateIndex": 57,
492        "ModifyIndex": 57
493    }
494]
495```
496