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