Type '/' to Search

»ACL Policy HTTP API

1.4.0+: The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is here.

The /acl/policy endpoints create, read, update, list and delete ACL policies in Consul.

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

»Create a Policy

This endpoint creates a new ACL policy.

MethodPathProduces
PUT/acl/policyapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneacl:write

The corresponding CLI command is consul acl policy create.

»Query Parameters

»JSON Request Body Schema

  • Name (string: <required>) - Specifies a name for the ACL policy. The name can contain alphanumeric characters, dashes -, and underscores _. This name must be unique.

  • Description (string: "") - Free form human readable description of the policy.

  • Rules (string: "") - Specifies rules for the ACL policy. The format of the Rules property is detailed in the ACL Rules documentation.

  • Datacenters (array<string>) - Specifies the datacenters the policy is valid within. When no datacenters are provided the policy is valid in all datacenters including those which do not yet exist but may in the future.

  • Namespace (string: "")

    Enterprise
    - Specifies the namespace of the policy you create. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

»Sample Payload

{
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"]
}

{
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"]
}

»Sample Request

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

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

»Sample Response

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

»Read a Policy

This endpoint reads an ACL policy with the given ID.

MethodPathProduces
GET/acl/policy/:idapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneacl:read

The corresponding CLI command is consul acl policy read.

»Path Parameters

  • id (string: <required>) - Specifies the UUID of the policy you lookup.

»Query Parameters

»Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9fdc78f5

$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/e359bd81-baca-903e-7e64-1ccd9fdc78f5

»Sample Response

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

»Read a Policy by Name

This endpoint reads an ACL policy with the given ID.

MethodPathProduces
GET/acl/policy/name/:nameapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneacl:read

The corresponding CLI command is consul acl policy read -name=<string>.

»Path Parameters

  • name (string: <required>) - Specifies the name of the ACL policy to read.

»Query Parameters

»Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/name/node-read

$ curl --request GET http://127.0.0.1:8500/v1/acl/policy/name/node-read

»Sample Response

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

{
  "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
  "Name": "node-read",
  "Description": "Grants read access to all node information",
  "Rules": "node_prefix \"\" { policy = \"read\"}",
  "Datacenters": ["dc1"],
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 14
}

»Update a Policy

This endpoint updates an existing ACL policy.

MethodPathProduces
PUT/acl/policy/:idapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneacl:write

The corresponding CLI command is consul acl policy update.

»Path Parameters

  • id (string: <required>) - Specifies the UUID of the policy you update.

»Query Parameters

»JSON Request Body Schema

  • ID (string: <optional>) - If specified, this field must be an exact match with the id path parameter.

  • Name (string: <required>) - Specifies a name for the ACL policy. The name can only contain alphanumeric characters as well as - and _ and must be unique.

  • Description (string: "") - Free form human readable description of this policy.

  • Rules (string: "") - Specifies rules for this ACL policy. The format of the Rules property is detailed in the ACL Rules documentation.

  • Datacenters (array<string>) - Specifies the datacenters this policy is valid within. When no datacenters are provided the policy is valid in all datacenters including those which do not yet exist but may in the future.

  • Namespace (string: "")

    Enterprise
    - Specifies the namespace of the policy you update. This field takes precedence over the ns query parameter, one of several other methods to specify the namespace.

»Sample Payload

{
  "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
  "Name": "register-app-service",
  "Description": "Grants write permissions necessary to register the 'app' service",
  "Rules": "service \"app\" { policy = \"write\"}"
}

{
  "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
  "Name": "register-app-service",
  "Description": "Grants write permissions necessary to register the 'app' service",
  "Rules": "service \"app\" { policy = \"write\"}"
}

»Sample Request

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/policy/c01a1f82-44be-41b0-a686-685fb6e0f485

$ curl --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/policy/c01a1f82-44be-41b0-a686-685fb6e0f485

»Sample Response

{
  "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
  "Name": "register-app-service",
  "Description": "Grants write permissions necessary to register the 'app' service",
  "Rules": "service \"app\" { policy = \"write\"}",
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 28
}

{
  "ID": "c01a1f82-44be-41b0-a686-685fb6e0f485",
  "Name": "register-app-service",
  "Description": "Grants write permissions necessary to register the 'app' service",
  "Rules": "service \"app\" { policy = \"write\"}",
  "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
  "CreateIndex": 14,
  "ModifyIndex": 28
}

»Delete a Policy

This endpoint deletes an ACL policy.

MethodPathProduces
DELETE/acl/policy/:idapplication/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 QueriesConsistency ModesAgent CachingACL Required
NOnonenoneacl:write

The corresponding CLI command is consul acl policy delete.

»Path Parameters

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

»Query Parameters

»Sample Request

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/policy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

$ curl --request DELETE \
    http://127.0.0.1:8500/v1/acl/policy/8f246b77-f3e1-ff88-5b48-8ec93abf3e05

»Sample Response

true

true

»List Policies

This endpoint lists all the ACL policies.

MethodPathProduces
GET/acl/policiesapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnoneacl:read

The corresponding CLI command is consul acl policy list.

»Query Parameters

»Sample Request

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

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

»Sample Response

Note - The policies rules are not included in the listing and must be retrieved by the policy reading endpoint

[
  {
    "CreateIndex": 4,
    "Datacenters": null,
    "Description": "Builtin Policy that grants unlimited access",
    "Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=",
    "ID": "00000000-0000-0000-0000-000000000001",
    "ModifyIndex": 4,
    "Name": "global-management"
  },
  {
    "CreateIndex": 14,
    "Datacenters": ["dc1"],
    "Description": "Grants read access to all node information",
    "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
    "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
    "ModifyIndex": 14,
    "Name": "node-read"
  }
]

[
  {
    "CreateIndex": 4,
    "Datacenters": null,
    "Description": "Builtin Policy that grants unlimited access",
    "Hash": "swIQt6up+s0cV4kePfJ2aRdKCLaQyykF4Hl1Nfdeumk=",
    "ID": "00000000-0000-0000-0000-000000000001",
    "ModifyIndex": 4,
    "Name": "global-management"
  },
  {
    "CreateIndex": 14,
    "Datacenters": ["dc1"],
    "Description": "Grants read access to all node information",
    "Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
    "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
    "ModifyIndex": 14,
    "Name": "node-read"
  }
]

»Methods to Specify Namespace
Enterprise

ACL policy endpoints support several methods for specifying the namespace of the ACL policy resources with the following order of precedence:

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