--- layout: api page_title: ACL Binding Rules - HTTP API description: The /acl/binding-rules endpoints are used to configure and manage ACL binding rules. --- # ACL Binding Rules HTTP API The `/acl/binding-rules` and `/acl/binding-rule` endpoints are used to manage ACL Binding Rules. ## Read Binding Rule by Name This endpoint reads an ACL Binding Rule with the given name. This queries the Binding Rule that has been replicated to the region, and may lag behind the authoritative region. | Method | Path | Produces | | ------ | ---------------------------- | ------------------ | | `GET` | `/acl/binding-rule/:rule_id` | `application/json` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | Consistency Modes | ACL Required | | ---------------- | ----------------- | ------------ | | `YES` | `all` | `management` | ### Parameters - `:rule_id` `(string: )` - Specifies the ID of the ACL Binding Rule. This is specified as part of the path. ### Sample Request ```shell-session $ curl \ --header "X-Nomad-Token: " \ https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09 ``` ### Sample Response ```json { "AuthMethod": "example-acl-auth-method", "BindName": "role", "BindType": "role", "CreateIndex": 16, "CreateTime": "2022-12-16T10:29:07.248465Z", "Description": "updated-acl-binding-rule", "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09", "ModifyIndex": 17, "ModifyTime": "2022-12-19T16:40:52.602004Z", "Selector": "engineering in list.roles" } ``` ## List Binding Rules This endpoint lists all ACL Binding Rules. This lists the Binding Rules that have been replicated to the region, and may lag behind the authoritative region. | Method | Path | Produces | | ------ | ------------------- | ------------------ | | `GET` | `/acl/binding-rules` | `application/json` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | Consistency Modes | ACL Required | | ---------------- | ----------------- | ------------ | | `YES` | `all` | `management` | ### Sample Request ```shell-session $ curl \ --header "X-Nomad-Token: " \ https://localhost:4646/v1/acl/binding-rules ``` ### Sample Response ```json [ { "AuthMethod": "auth0", "CreateIndex": 16, "Description": "updated-acl-binding-rule", "Hash": "N7aEMsAfl3btWrZSwaWdzcRIAO3uRrRH2yQ8rPsuJ44=", "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09", "ModifyIndex": 17 } ] ``` ## Create Binding Rule This endpoint creates an ACL Binding Rule. The request is always forwarded to the authoritative region. | Method | Path | Produces | | ------ | ------------------- | ------------------ | | `POST` | `/acl/binding-rule` | `application/json` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ------------ | | `NO` | `management` | ### Parameters - `Description` `(string: "")` - Human-readable, operator set description that can provide additional context about the binding role. This is an operational field. - `AuthMethod` `(string: )` - Name of the auth method for which this rule applies to. This is a required field and the method must exist within state before the cluster administrator can create the rule. - `Selector` `(string: "")` - A boolean expression that matches against verified identity attributes returned from the auth method during login. This is optional and when not set, provides a catch-all rule. If set, it must be a valid [go-bexpr][] expression; for example, a dash in the claim name will require it to be encased in quotes and escaped such as `"\"project-developer\" in list.roles"`. ~> **Caveat:** Selectors that operate on `ClaimMappings` (as opposed to `ListClaimMappings`), the key that we match against has to be prefixed with `value.` (e.g. `value.owner == username` for a claim mapping that has `owner` as its key). - `BindType` `(string: )` - Adjusts how this binding rule is applied at login time. Valid values are `role`, `policy`, and `management`. - `BindName` `(string: )` - Target of the binding. Can be lightly templated using HIL ${foo} syntax from available field names. If the bind type is set to `management`, this should not be set. How it is used depends on the BindType. ### Sample Payload ```json { "Description": "example-acl-binding-rule", "AuthMethod": "auth0", "Selector": "engineering in list.roles", "BindType": "role", "BindName": "eng-ro", } ``` ### Sample Request ```shell-session $ curl \ --request POST \ --header "X-Nomad-Token: " \ --data @payload.json \ https://localhost:4646/v1/acl/binding-rule ``` ### Sample Response ```json { "AuthMethod": "auth0", "BindName": "eng-ro", "BindType": "role", "CreateIndex": 16, "CreateTime": "2022-12-16T10:29:07.248465Z", "Description": "example-acl-binding-rule", "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09", "ModifyIndex": 16, "ModifyTime": "2022-12-16T10:29:07.248465Z", "Selector": "engineering in list.roles" } ``` ## Update Binding Rule This endpoint updates an existing ACL Binding Rule. The request is always forwarded to the authoritative region. | Method | Path | Produces | | ------ | ------------------------------ | ------------------ | | `POST` | `/acl/binding-rule/:rule_id` | `application/json` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ------------ | | `NO` | `management` | ### Parameters - `Description` `(string: "")` - Human-readable, operator set description that can provide additional context about the binding role. This is an operational field. - `Selector` `(string: "")` - A boolean expression that matches against verified identity attributes returned from the auth method during login. This is optional and when not set, provides a catch-all rule. If set, it must be a valid [go-bexpr][] expression; for example, a dash in the claim name will require it to be encased in quotes and escaped such as `"\"project-developer\" in list.roles"`. - `BindType` `(string: "")` - Adjusts how this binding rule is applied at login time. Valid values are `role`, `policy`, and `management`. - `BindName` `(string: "")` - Target of the binding. Can be lightly templated using HIL ${foo} syntax from available field names. How it is used depends on the BindType. ### Sample Payload ```json { "Description": "new description", } ``` ### Sample Request ```shell-session $ curl \ --request POST \ --header "X-Nomad-Token: " \ --data @payload.json \ https://localhost:4646/v1/acl/binding-rule/example-acl-binding-rule ``` ### Sample Response ```json { "AuthMethod": "auth0", "BindName": "eng-ro", "BindType": "role", "CreateIndex": 16, "CreateTime": "2022-12-16T10:29:07.248465Z", "Description": "new description", "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09", "ModifyIndex": 17, "ModifyTime": "2022-12-19T16:40:52.602004Z", "Selector":"engineering in list.roles" } ``` ## Delete Binding Rule This endpoint deletes the ACL Binding Rule as identified by its ID. This request is always forwarded to the authoritative region. | Method | Path | Produces | | -------- | ---------------------------- | -------------- | | `DELETE` | `/acl/binding-rule/:rule_id` | `(empty body)` | The table below shows this endpoint's support for [blocking queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls). | Blocking Queries | ACL Required | | ---------------- | ------------ | | `NO` | `management` | ### Parameters - `rule_id` `(string: )` - Specifies the ID of Binding Rule to delete and is specified as part of the path. ### Sample Request ```shell-session $ curl \ --request DELETE \ --header "X-Nomad-Token: " \ https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09 ``` [go-bexpr]: https://github.com/hashicorp/go-bexpr