A new platform for documentation and tutorials is launching soon.

We are migrating Consul documentation into HashiCorp Developer, our new developer experience.

»ACL Binding Rule HTTP API

1.5.0+: The binding rule APIs are available in Consul versions 1.5.0 and newer.

The /acl/binding-rule endpoints create, read, update, list and delete ACL binding rules in Consul.

For more information on how to setup ACLs, please check the ACL tutorial.

»Create a Binding Rule

This endpoint creates a new ACL binding rule.

Method	Path	Produces
`PUT`	`/acl/binding-rule`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:write`

The corresponding CLI command is consul acl binding-rule create.

»Query Parameters

ns (string: "")
Enterprise
- Specifies the namespace of the binding rule you create. You can also specify the namespace through other methods.

»JSON Request Body Schema

Description (string: "") - Free form human readable description of the binding rule.
AuthMethod (string: <required>) - The name of the auth method that this rule applies to. This field is immutable.
Selector (string: "") - Specifies the expression used to match this rule against valid identities returned from an auth method validation. If empty this binding rule matches all valid identities returned from the auth method. For example:
```
serviceaccount.namespace==default and serviceaccount.name!=vault
```
```
serviceaccount.namespace==default and serviceaccount.name!=vault
```

BindType (string: <required>) - Specifies the way the binding rule affects a token created at login.

BindType=service - The computed bind name value is used as an ACLServiceIdentity.ServiceName field in the token that is created.

{ ...other fields...
    "ServiceIdentities": [
        { "ServiceName": "<computed BindName>" }
    ]
}

{ ...other fields...
    "ServiceIdentities": [
        { "ServiceName": "<computed BindName>" }
    ]
}

BindType=node - The computed bind name value is used as an ACLNodeIdentity.NodeName field in the token that is created.

{ ...other fields...
    "NodeIdentities": [
        { "NodeName": "<computed BindName>", "Datacenter": "<local datacenter>" }
    ]
}

{ ...other fields...
    "NodeIdentities": [
        { "NodeName": "<computed BindName>", "Datacenter": "<local datacenter>" }
    ]
}

BindType=role - The computed bind name value is used as a RoleLink.Name field in the token that is created. This binding rule will only apply if a role with the given name exists at login-time. If it does not then this rule is ignored.
```
{ ...other fields...
    "Roles": [
        { "Name": "<computed BindName>" }
    ]
}
```
```
{ ...other fields...
    "Roles": [
        { "Name": "<computed BindName>" }
    ]
}
```

BindName (string: <required>) - The name to bind to a token at login-time. What it binds to can be adjusted with different values of the BindType field. This can either be a plain string or lightly templated using HIL syntax to interpolate the same values that are usable by the Selector syntax. For example:
```
prefixed-${serviceaccount.name}
```
```
prefixed-${serviceaccount.name}
```
Namespace (string: "")
Enterprise
- Specifies the namespace of the binding rule you create. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

»Sample Payload

{
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}"
}

{
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}"
}

»Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/binding-rule

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/binding-rule

»Sample Response

{
  "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}",
  "CreateIndex": 17,
  "ModifyIndex": 17
}

{
  "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}",
  "CreateIndex": 17,
  "ModifyIndex": 17
}

»Read a Binding Rule

This endpoint reads an ACL binding rule with the given ID. If no binding rule exists with the given ID, a 404 is returned instead of a 200 response.

Method	Path	Produces
`GET`	`/acl/binding-rule/:id`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`acl:read`

The corresponding CLI command is consul acl binding-rule read.

»Path Parameters

id (string: <required>) - Specifies the UUID of the ACL binding rule to read.

»Query Parameters

ns (string: "")
Enterprise
- Specifies the namespace of the binding rule you lookup. You can also specify the namespace through other methods.

»Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

$ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

»Sample Response

{
  "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}",
  "CreateIndex": 17,
  "ModifyIndex": 17
}

{
  "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
  "Description": "example rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace==default",
  "BindType": "service",
  "BindName": "{{ serviceaccount.name }}",
  "CreateIndex": 17,
  "ModifyIndex": 17
}

»Update a Binding Rule

This endpoint updates an existing ACL binding rule.

Method	Path	Produces
`PUT`	`/acl/binding-rule/:id`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:write`

The corresponding CLI command is consul acl binding-rule update.

»Path Parameters

id (string: <required>) - Specifies the UUID of the ACL binding rule you update.

»Query Parameters

ns (string: "")
Enterprise
- Specifies the namespace of the binding rule you update. You can also specify the namespace through other methods.

»JSON Request Body Schema

ID (string: <optional>) - If specified, this field must be an exact match with the id path parameter.
Description (string: "") - Free form human readable description of the binding rule.
AuthMethod (string: <required>) - Specifies the name of the auth method that this rule applies to. This field is immutable so if present in the body then it must match the existing value. If not present then the value will be filled in by Consul.
Selector (string: "") - Specifies the expression used to match this rule against valid identities returned from an auth method validation. If empty this binding rule matches all valid identities returned from the auth method. For example:
```
serviceaccount.namespace==default and serviceaccount.name!=vault
```
```
serviceaccount.namespace==default and serviceaccount.name!=vault
```

BindType (string: <required>) - Specifies the way the binding rule affects a token created at login.

BindType=service - The computed bind name value is used as an ACLServiceIdentity.ServiceName field in the token that is created.

{ ...other fields...
    "ServiceIdentities": [
        { "ServiceName": "<computed BindName>" }
    ]
}

{ ...other fields...
    "ServiceIdentities": [
        { "ServiceName": "<computed BindName>" }
    ]
}

BindType=node - The computed bind name value is used as an ACLNodeIdentity.NodeName field in the token that is created.

{ ...other fields...
    "NodeIdentities": [
        { "NodeName": "<computed BindName>", "Datacenter": "<local datacenter>" }
    ]
}

{ ...other fields...
    "NodeIdentities": [
        { "NodeName": "<computed BindName>", "Datacenter": "<local datacenter>" }
    ]
}

BindType=role - The computed bind name value is used as a RoleLink.Name field in the token that is created. This binding rule will only apply if a role with the given name exists at login-time. If it does not then this rule is ignored.
```
{ ...other fields...
    "Roles": [
        { "Name": "<computed BindName>" }
    ]
}
```
```
{ ...other fields...
    "Roles": [
        { "Name": "<computed BindName>" }
    ]
}
```

BindName (string: <required>) - The name to bind to a token at login-time. What it binds to can be adjusted with different values of the BindType field. This can either be a plain string or lightly templated using HIL syntax to interpolate the same values that are usable by the Selector syntax. For example:
```
prefixed-${serviceaccount.name}
```
```
prefixed-${serviceaccount.name}
```
Namespace (string: "")
Enterprise
- Specifies the namespace of the binding rule you update. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

»Sample Payload

{
  "Description": "updated rule",
  "Selector": "serviceaccount.namespace=dev",
  "BindType": "role",
  "BindName": "{{ serviceaccount.name }}"
}

{
  "Description": "updated rule",
  "Selector": "serviceaccount.namespace=dev",
  "BindType": "role",
  "BindName": "{{ serviceaccount.name }}"
}

»Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

»Sample Response

{
  "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
  "Description": "updated rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace=dev",
  "BindType": "role",
  "BindName": "{{ serviceaccount.name }}",
  "CreateIndex": 17,
  "ModifyIndex": 18
}

{
  "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
  "Description": "updated rule",
  "AuthMethod": "minikube",
  "Selector": "serviceaccount.namespace=dev",
  "BindType": "role",
  "BindName": "{{ serviceaccount.name }}",
  "CreateIndex": 17,
  "ModifyIndex": 18
}

»Delete a Binding Rule

This endpoint deletes an ACL binding rule.

Method	Path	Produces
`DELETE`	`/acl/binding-rule/:id`	`application/json`

Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded.

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`none`	`none`	`acl:write`

The corresponding CLI command is consul acl binding-rule delete.

»Path Parameters

id (string: <required>) - Specifies the UUID of the binding rule you delete.

»Query Parameters

ns (string: "")
Enterprise
- Specifies the namespace of the binding rule you delete. You can also specify the namespace through other methods.

»Sample Request

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/binding-rule/000ed53c-e2d3-e7e6-31a5-c19bc3518a3d

»Sample Response

true

true

»List Binding Rules

This endpoint lists all the ACL binding rules.

Method	Path	Produces
`GET`	`/acl/binding-rules`	`application/json`

The table below shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`YES`	`all`	`none`	`acl:read`

The corresponding CLI command is consul acl binding-rule list.

»Query Parameters

authmethod (string: "") - Filters the binding rule list to those binding rules that are linked with the specific named auth method.
ns (string: "")
Enterprise
- Return only the binding rules in the specified namespace. The namespace may be specified as '*' to return results for all namespaces. You can also specify the namespace through other methods.

»Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rules

$ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rules

»Sample Response

[
  {
    "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
    "Description": "example 1",
    "AuthMethod": "minikube-1",
    "BindType": "service",
    "BindName": "k8s-{{ serviceaccount.name }}",
    "CreateIndex": 17,
    "ModifyIndex": 17
  },
  {
    "ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa",
    "Description": "example 2",
    "AuthMethod": "minikube-2",
    "BindType": "service",
    "Selector": "serviceaccount.namespace==default",
    "BindName": "k8s-{{ serviceaccount.name }}",
    "CreateIndex": 18,
    "ModifyIndex": 18
  }
]

[
  {
    "ID": "000ed53c-e2d3-e7e6-31a5-c19bc3518a3d",
    "Description": "example 1",
    "AuthMethod": "minikube-1",
    "BindType": "service",
    "BindName": "k8s-{{ serviceaccount.name }}",
    "CreateIndex": 17,
    "ModifyIndex": 17
  },
  {
    "ID": "b4f0a0a3-69f2-7a4f-6bef-326034ace9fa",
    "Description": "example 2",
    "AuthMethod": "minikube-2",
    "BindType": "service",
    "Selector": "serviceaccount.namespace==default",
    "BindName": "k8s-{{ serviceaccount.name }}",
    "CreateIndex": 18,
    "ModifyIndex": 18
  }
]

»Methods to Specify Namespace
Enterprise

Binding rule create, read, update, and delete endpoints support several methods for specifying the namespace of the auth method resource with the following order of precedence:

Namespace field of the JSON request body - only applies to create and update endpoints
ns query parameter
X-Consul-Namespace request header
Namespace is inherited from the namespace of the request's ACL token (if any)
The default namespace

»ACL Binding Rule HTTP API

»Create a Binding Rule

»Query Parameters

»JSON Request Body Schema

»Sample Payload

»Sample Request

»Sample Response

»Read a Binding Rule

»Path Parameters

»Query Parameters

»Sample Request

»Sample Response

»Update a Binding Rule

»Path Parameters

»Query Parameters

»JSON Request Body Schema

»Sample Payload

»Sample Request

»Sample Response

»Delete a Binding Rule

»Path Parameters

»Query Parameters

»Sample Request

»Sample Response

»List Binding Rules

»Query Parameters

»Sample Request

»Sample Response

»Methods to Specify Namespace Enterprise

»Methods to Specify Namespace
Enterprise