1--- 2layout: api 3page_title: ACL Binding Rules - HTTP API 4sidebar_current: api-acl-binding-rules 5description: |- 6 The /acl/binding-rule endpoints manage Consul's ACL Binding Rules. 7--- 8 9-> **1.5.0+:** The binding rule APIs are available in Consul versions 1.5.0 and newer. 10 11# ACL Binding Rule HTTP API 12 13The `/acl/binding-rule` endpoints [create](#create-a-binding-rule), 14[read](#read-a-binding-rule), [update](#update-a-binding-rule), 15[list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding 16rules in Consul. 17 18For more information on how to setup ACLs, please see 19the [ACL Guide](https://learn.hashicorp.com/consul/advanced/day-1-operations/production-acls). 20 21## Create a Binding Rule 22 23This endpoint creates a new ACL binding rule. 24 25| Method | Path | Produces | 26| ------ | ---------------------------- | -------------------------- | 27| `PUT` | `/acl/binding-rule` | `application/json` | 28 29The table below shows this endpoint's support for 30[blocking queries](/api/features/blocking.html), 31[consistency modes](/api/features/consistency.html), 32[agent caching](/api/features/caching.html), and 33[required ACLs](/api/index.html#authentication). 34 35| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 36| ---------------- | ----------------- | ------------- | ------------ | 37| `NO` | `none` | `none` | `acl:write` | 38 39### Parameters 40 41- `Description` `(string: "")` - Free form human readable description of the binding rule. 42 43- `AuthMethod` `(string: <required>)` - The name of the auth method that this 44 rule applies to. This field is immutable. 45 46- `Selector` `(string: "")` - Specifies the expression used to match this rule 47 against valid identities returned from an auth method validation. If empty 48 this binding rule matches all valid identities returned from the auth method. For example: 49 50 ```text 51 serviceaccount.namespace==default and serviceaccount.name!=vault 52 ``` 53 54- `BindType` `(string: <required>)` - Specifies the way the binding rule 55 affects a token created at login. 56 57 - `BindType=service` - The computed bind name value is used as an 58 `ACLServiceIdentity.ServiceName` field in the token that is created. 59 60 ```json 61 { ...other fields... 62 "ServiceIdentities": [ 63 { "ServiceName": "<computed BindName>" } 64 ] 65 } 66 ``` 67 68 - `BindType=role` - The computed bind name value is used as a `RoleLink.Name` 69 field in the token that is created. This binding rule will only apply if a 70 role with the given name exists at login-time. If it does not then this 71 rule is ignored. 72 73 ```json 74 { ...other fields... 75 "Roles": [ 76 { "Name": "<computed BindName>" } 77 ] 78 } 79 ``` 80 81- `BindName` `(string: <required>)` - The name to bind to a token at 82 login-time. What it binds to can be adjusted with different values of the 83 `BindType` field. This can either be a plain string or lightly templated 84 using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same 85 values that are usable by the `Selector` syntax. For example: 86 87 ```text 88 prefixed-${serviceaccount.name} 89 ``` 90 91- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace to 92 create the binding rule. If not provided in the JSON body, the value of 93 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 94 If not provided at all, the namespace will be inherited from the request's ACL 95 token or will default to the `default` namespace. Added in Consul 1.7.0. 96 97### Sample Payload 98 99```json 100{ 101 "Description": "example rule", 102 "AuthMethod": "minikube", 103 "Selector": "serviceaccount.namespace==default", 104 "BindType": "service", 105 "BindName": "{{ serviceaccount.name }}" 106} 107``` 108 109### Sample Request 110 111```sh 112$ curl -X PUT \ 113 --data @payload.json \ 114 http://127.0.0.1:8500/v1/acl/binding-rule 115``` 116 117### Sample Response 118 119```json 120{ 121 "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", 122 "Description": "example rule", 123 "AuthMethod": "minikube", 124 "Selector": "serviceaccount.namespace==default", 125 "BindType": "service", 126 "BindName": "{{ serviceaccount.name }}", 127 "CreateIndex": 17, 128 "ModifyIndex": 17 129} 130``` 131 132## Read a Binding Rule 133 134This endpoint reads an ACL binding rule with the given ID. If no 135binding rule exists with the given ID, a 404 is returned instead of a 200 136response. 137 138| Method | Path | Produces | 139| ------ | ---------------------------- | -------------------------- | 140| `GET` | `/acl/binding-rule/:id` | `application/json` | 141 142The table below shows this endpoint's support for 143[blocking queries](/api/features/blocking.html), 144[consistency modes](/api/features/consistency.html), 145[agent caching](/api/features/caching.html), and 146[required ACLs](/api/index.html#authentication). 147 148| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 149| ---------------- | ----------------- | ------------- | ------------ | 150| `YES` | `all` | `none` | `acl:read` | 151 152### Parameters 153 154- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule 155 to read. This is required and is specified as part of the URL path. 156 157- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to lookup 158 the binding rule. This value can be specified as the `ns` URL query 159 parameter or the `X-Consul-Namespace` header. If not provided by either, 160 the namespace will be inherited from the request's ACL token or will default 161 to the `default` namespace. Added in Consul 1.7.0. 162 163 164### Sample Request 165 166```sh 167$ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d 168``` 169 170### Sample Response 171 172```json 173{ 174 "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", 175 "Description": "example rule", 176 "AuthMethod": "minikube", 177 "Selector": "serviceaccount.namespace==default", 178 "BindType": "service", 179 "BindName": "{{ serviceaccount.name }}", 180 "CreateIndex": 17, 181 "ModifyIndex": 17 182} 183``` 184 185## Update a Binding Rule 186 187This endpoint updates an existing ACL binding rule. 188 189| Method | Path | Produces | 190| ------ | ---------------------------- | -------------------------- | 191| `PUT` | `/acl/binding-rule/:id` | `application/json` | 192 193The table below shows this endpoint's support for 194[blocking queries](/api/features/blocking.html), 195[consistency modes](/api/features/consistency.html), 196[agent caching](/api/features/caching.html), and 197[required ACLs](/api/index.html#authentication). 198 199| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 200| ---------------- | ----------------- | ------------- | ------------ | 201| `NO` | `none` | `none` | `acl:write` | 202 203### Parameters 204 205- `ID` `(string: <required>)` - Specifies the ID of the binding rule to update. 206 This is required in the URL path but may also be specified in the JSON body. 207 If specified in both places then they must match exactly. 208 209- `Description` `(string: "")` - Free form human readable description of the binding rule. 210 211- `AuthMethod` `(string: <required>)` - Specifies the name of the auth 212 method that this rule applies to. This field is immutable so if present in 213 the body then it must match the existing value. If not present then the value 214 will be filled in by Consul. 215 216- `Selector` `(string: "")` - Specifies the expression used to match this rule 217 against valid identities returned from an auth method validation. If empty 218 this binding rule matches all valid identities returned from the auth method. For example: 219 220 ```text 221 serviceaccount.namespace==default and serviceaccount.name!=vault 222 ``` 223 224- `BindType` `(string: <required>)` - Specifies the way the binding rule 225 affects a token created at login. 226 227 - `BindType=service` - The computed bind name value is used as an 228 `ACLServiceIdentity.ServiceName` field in the token that is created. 229 230 ```json 231 { ...other fields... 232 "ServiceIdentities": [ 233 { "ServiceName": "<computed BindName>" } 234 ] 235 } 236 ``` 237 238 - `BindType=role` - The computed bind name value is used as a `RoleLink.Name` 239 field in the token that is created. This binding rule will only apply if a 240 role with the given name exists at login-time. If it does not then this 241 rule is ignored. 242 243 ```json 244 { ...other fields... 245 "Roles": [ 246 { "Name": "<computed BindName>" } 247 ] 248 } 249 ``` 250 251- `BindName` `(string: <required>)` - The name to bind to a token at 252 login-time. What it binds to can be adjusted with different values of the 253 `BindType` field. This can either be a plain string or lightly templated 254 using [HIL syntax](https://github.com/hashicorp/hil) to interpolate the same 255 values that are usable by the `Selector` syntax. For example: 256 257 ```text 258 prefixed-${serviceaccount.name} 259 ``` 260 261- `Namespace` `(string: "")` - **(Enterprise Only)** Specifies the namespace of 262 the binding rule to update. If not provided in the JSON body, the value of 263 the `ns` URL query parameter or in the `X-Consul-Namespace` header will be used. 264 If not provided at all, the namespace will be inherited from the request's ACL 265 token or will default to the `default` namespace. Added in Consul 1.7.0. 266 267### Sample Payload 268 269```json 270{ 271 "Description": "updated rule", 272 "Selector": "serviceaccount.namespace=dev", 273 "BindType": "role", 274 "BindName": "{{ serviceaccount.name }}" 275} 276``` 277 278### Sample Request 279 280```sh 281$ curl -X PUT \ 282 --data @payload.json \ 283 http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d 284``` 285 286### Sample Response 287 288```json 289{ 290 "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", 291 "Description": "updated rule", 292 "AuthMethod": "minikube", 293 "Selector": "serviceaccount.namespace=dev", 294 "BindType": "role", 295 "BindName": "{{ serviceaccount.name }}", 296 "CreateIndex": 17, 297 "ModifyIndex": 18 298} 299``` 300 301## Delete a Binding Rule 302 303This endpoint deletes an ACL binding rule. 304 305| Method | Path | Produces | 306| -------- | ------------------------- | -------------------------- | 307| `DELETE` | `/acl/binding-rule/:id` | `application/json` | 308 309Even though the return type is application/json, the value is either true or 310false indicating whether the delete succeeded. 311 312The table below shows this endpoint's support for 313[blocking queries](/api/features/blocking.html), 314[consistency modes](/api/features/consistency.html), 315[agent caching](/api/features/caching.html), and 316[required ACLs](/api/index.html#authentication). 317 318| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 319| ---------------- | ----------------- | ------------- | ------------ | 320| `NO` | `none` | `none` | `acl:write` | 321 322### Parameters 323 324- `id` `(string: <required>)` - Specifies the UUID of the ACL binding rule to 325 delete. This is required and is specified as part of the URL path. 326 327- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace of the 328 binding rule to delete. This value can be specified as the `ns` URL query 329 parameter or the `X-Consul-Namespace` header. If not provided by either, 330 the namespace will be inherited from the request's ACL token or will default 331 to the `default` namespace. Added in Consul 1.7.0. 332 333### Sample Request 334 335```sh 336$ curl -X DELETE \ 337 http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d 338``` 339 340### Sample Response 341```json 342true 343``` 344 345## List Binding Rules 346 347This endpoint lists all the ACL binding rules. 348 349| Method | Path | Produces | 350| ------ | ---------------------------- | -------------------------- | 351| `GET` | `/acl/binding-rules` | `application/json` | 352 353The table below shows this endpoint's support for 354[blocking queries](/api/features/blocking.html), 355[consistency modes](/api/features/consistency.html), 356[agent caching](/api/features/caching.html), and 357[required ACLs](/api/index.html#authentication). 358 359| Blocking Queries | Consistency Modes | Agent Caching | ACL Required | 360| ---------------- | ----------------- | ------------- | ------------ | 361| `YES` | `all` | `none` | `acl:read` | 362 363## Parameters 364 365- `authmethod` `(string: "")` - Filters the binding rule list to those binding 366 rules that are linked with the specific named auth method. 367 368- `ns` `(string: "")` - **(Enterprise Only)** Specifies the namespace to list 369 the binding rules for. This value can be specified as the `ns` URL query 370 parameter or the `X-Consul-Namespace` header. If not provided by either, 371 the namespace will be inherited from the request's ACL token or will default 372 to the `default` namespace. The namespace may be specified as '*' and then 373 results will be returned for all namespaces. Added in Consul 1.7.0. 374 375## Sample Request 376 377```sh 378$ curl -X GET http://127.0.0.1:8500/v1/acl/binding-rules 379``` 380 381### Sample Response 382 383```json 384[ 385 { 386 "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d", 387 "Description": "example 1", 388 "AuthMethod": "minikube-1", 389 "BindType": "service", 390 "BindName": "k8s-{{ serviceaccount.name }}", 391 "CreateIndex": 17, 392 "ModifyIndex": 17 393 }, 394 { 395 "ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa", 396 "Description": "example 2", 397 "AuthMethod": "minikube-2", 398 "Selector": "serviceaccount.namespace==default", 399 "BindName": "k8s-{{ serviceaccount.name }}", 400 "CreateIndex": 18, 401 "ModifyIndex": 18 402 } 403] 404``` 405