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