• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Consul
  • Install
  • Tutorials
  • Documentation
  • API
  • CLI
  • Try Cloud(opens in new tab)
  • Sign up
Consul Home

API

Skip to main content
  • API
  • API Structure

    • Overview
    • Tokens
    • Legacy Tokens
    • Policies
    • Roles
    • Auth Methods
    • Binding Rules
  • Admin Partitions
  • Catalog
  • Cluster Peering
  • Config
  • Coordinates
  • Discovery Chain
  • Events
  • Health
  • KV Store
  • Namespaces
  • Prepared Queries
  • Sessions
  • Snapshots
  • Status
  • Transactions

  • Libraries & SDKs

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Consul
  3. API
  4. ACLs
  5. Legacy Tokens
  • Consul
  • v1.13.x
  • v1.12.x
  • v1.11.x
  • v1.10.x
  • v1.9.x
  • v1.8.x

ยปACL HTTP API

The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0. It's strongly recommended you do not build anything using the legacy system and use the new ACL Token and Policy APIs instead.

The legacy /acl endpoints to create, update, destroy, and query legacy ACL tokens in Consul.

For more information about ACLs, please check the ACL tutorial.

Create ACL Token

This endpoint makes a new ACL token.

MethodPathProduces
PUT/acl/createapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonemanagement

Parameters

  • ID (string: "") - Specifies the ID of the ACL. If not provided, a UUID is generated.

  • Name (string: "") - Specifies a human-friendly name for the ACL token.

  • Type (string: "client") - Specifies the type of ACL token. Valid values are: client and management.

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

Sample Payload

{
  "Name": "my-app-token",
  "Type": "client",
  "Rules": ""
}

Sample Request

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

Sample Response

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

Update ACL Token

This endpoint is used to modify the policy for a given ACL token. Instead of generating a new token ID, the ID field must be provided.

MethodPathProduces
PUT/acl/updateapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonemanagement

Parameters

The parameters are the same as the create endpoint, except the ID field is required.

Sample Payload

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
  "Name": "my-app-token-updated",
  "Type": "client",
  "Rules": "# New Rules"
}

Sample Request

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

Sample Response

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

Delete ACL Token

This endpoint deletes an ACL token with the given ID.

MethodPathProduces
PUT/acl/destroy/:uuidapplication/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
NOnonenonemanagement

Parameters

  • uuid (string: <required>) - Specifies the UUID of the ACL token to destroy. This is required and is specified as part of the URL path.

Sample Request

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

Sample Response

true

Read ACL Token

This endpoint reads an ACL token with the given ID.

MethodPathProduces
GET/acl/info/:uuidapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonenone

Note: No ACL is required because the ACL is specified in the URL path.

Parameters

  • uuid (string: <required>) - Specifies the UUID of the ACL token to read. This is required and is specified as part of the URL path.

Sample Request

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

Sample Response

[
  {
    "CreateIndex": 3,
    "ModifyIndex": 3,
    "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
    "Name": "Client Token",
    "Type": "client",
    "Rules": "..."
  }
]

Clone ACL Token

This endpoint clones an ACL and returns a new token ID. This allows a token to serve as a template for others, making it simple to generate new tokens without complex rule management.

MethodPathProduces
PUT/acl/clone/:uuidapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenonemanagement

Parameters

  • uuid (string: <required>) - Specifies the UUID of the ACL token to be cloned. This is required and is specified as part of the URL path.

Sample Request

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

Sample Response

{
  "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e"
}

List ACLs

This endpoint lists all the active ACL tokens.

MethodPathProduces
GET/acl/listapplication/json

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

Blocking QueriesConsistency ModesAgent CachingACL Required
YESallnonemanagement

Sample Request

$ curl \
    http://127.0.0.1:8500/v1/acl/list

Sample Response

[
  {
    "CreateIndex": 3,
    "ModifyIndex": 3,
    "ID": "8f246b77-f3e1-ff88-5b48-8ec93abf3e05",
    "Name": "Client Token",
    "Type": "client",
    "Rules": "..."
  }
]

Check ACL Replication

The check ACL replication endpoint has not changed between the legacy system and the new system. Review the latest documentation to learn more about this endpoint.

Edit this page on GitHub

On this page

  1. ACL HTTP API
  2. Create ACL Token
  3. Update ACL Token
  4. Delete ACL Token
  5. Read ACL Token
  6. Clone ACL Token
  7. List ACLs
  8. Check ACL Replication
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)