» ACL Token HTTP API

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

For more information about ACLs, please see the ACL Guide.

» Create a Token

This endpoint creates a new ACL token.

Method Path Produces
PUT /acl/token 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

» Parameters

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

  • Policies (array<PolicyLink>) - The list of policies that should be applied to the token. A PolicyLink is an object with an "ID" and/or "Name" field to specify a policy. With the PolicyLink, tokens can be linked to policies either by the policy name or by the policy ID. When policies are linked by name they will be internally resolved to the policy ID. With linking tokens internally by IDs, Consul enables policy renaming without breaking tokens.

  • Local (bool: false) - If true, indicates that the token should not be replicated globally and instead be local to the current datacenter.

» Sample Payload

{
   "Description": "Agent token for 'node1'",
   "Policies": [
      {
         "ID": "165d4317-e379-f732-ce70-86278c4558f7"
      },
      {
         "Name": "node-read"
      }
   ],
   "Local": false
}

» Sample Request

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

» Sample Response

{
    "AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
    "SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
    "Description": "Agent token for 'node1'",
    "Policies": [
        {
            "ID": "165d4317-e379-f732-ce70-86278c4558f7",
            "Name": "node1-write"
        },
        {
            "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
            "Name": "node-read"
        }
    ],
    "Local": false,
    "CreateTime": "2018-10-24T12:25:06.921933-04:00",
    "Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
    "CreateIndex": 59,
    "ModifyIndex": 59
}

» Read a Token

This endpoint reads an ACL token with the given Accessor ID.

Method Path Produces
GET /acl/token/:AccessorID 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

» Parameters

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

» Sample Request

$ curl -X GET http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511

» Sample Response

{
    "AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
    "SecretID": "<hidden>",
    "Description": "Agent token for 'node1'",
    "Policies": [
        {
            "ID": "165d4317-e379-f732-ce70-86278c4558f7",
            "Name": "node1-write"
        },
        {
            "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
            "Name": "node-read"
        }
    ],
    "Local": false,
    "CreateTime": "2018-10-24T12:25:06.921933-04:00",
    "Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
    "CreateIndex": 59,
    "ModifyIndex": 59
}

» Read Self Token

This endpoint returns the ACL token details that matches the secret ID specified with the X-Consul-Token header or the token query parameter.

Method Path Produces
GET /acl/token/:AccessorID 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 none

» Sample Request

$ curl -H "X-Consul-Token: 6a1253d2-1785-24fd-91c2-f8e78c745511" \
   http://127.0.0.1:8500/v1/acl/token/self

» Sample Response

{
    "AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
    "SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
    "Description": "Agent token for 'node1'",
    "Policies": [
        {
            "ID": "165d4317-e379-f732-ce70-86278c4558f7",
            "Name": "node1-write"
        },
        {
            "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
            "Name": "node-read"
        }
    ],
    "Local": false,
    "CreateTime": "2018-10-24T12:25:06.921933-04:00",
    "Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
    "CreateIndex": 59,
    "ModifyIndex": 59
}

» Update a Token

This endpoint updates an existing ACL token.

Method Path Produces
PUT /acl/token/:AccessorID 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

» Parameters

  • AccessorID (string: "") - Specifies the accessor ID of the token being updated. This is required in the URL path but may also be specified in the JSON body. If specified in both places then they must match exactly. This field is immutable. If not present in the body and only in the URL then it will be filled in by Consul.

  • SecretID (string: "") - Specifies the secret ID of the token being updated. 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.

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

  • Policies (array<PolicyLink>) - This is the list of policies that should be applied to this token. A PolicyLink is an object with an "ID" and/or "Name" field to specify a policy. With this tokens can be linked to policies either by the policy name or by the policy ID. When policies are linked by name they will internally be resolved to the policy ID. With linking tokens internally by IDs, Consul enables policy renaming without breaking tokens.

  • Local (bool: false) - If true, indicates that this token should not be replicated globally and instead be local to the current datacenter. This value must match the existing value or the request will return an error.

» Sample Payload

{
   "Description": "Agent token for 'node1'",
   "Policies": [
      {
         "ID": "165d4317-e379-f732-ce70-86278c4558f7"
      },
      {
         "Name": "node-read"
      },
      {
         "Name": "service-read"
      }
   ],
   "Local": false
}

» Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511

» Sample Response

{
    "AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
    "SecretID": "45a3bd52-07c7-47a4-52fd-0745e0cfe967",
    "Description": "Agent token for 'node1'",
    "Policies": [
        {
            "ID": "165d4317-e379-f732-ce70-86278c4558f7",
            "Name": "node1-write"
        },
        {
            "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
            "Name": "node-read"
        },
        {
            "ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
            "Name": "service-read"
        }
    ],
    "Local": false,
    "CreateTime": "2018-10-24T12:25:06.921933-04:00",
    "Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
    "CreateIndex": 59,
    "ModifyIndex": 100
}

» Clone a Token

This endpoint clones an existing ACL token.

Method Path Produces
PUT /acl/token/:AccessorID/clone 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

» Parameters

  • AccessorID (string: <required>) - The accessor ID of the token to clone. This is required in the URL path

  • Description (string: "") - Free form human readable description for the cloned token.

» Sample Payload

{
   "Description": "Clone of Agent token for 'node1'",
}

» Sample Request

$ curl \
    --request PUT \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl/token/6a1253d2-1785-24fd-91c2-f8e78c745511/clone

» Sample Response

{
    "AccessorID": "773efe2a-1f6f-451f-878c-71be10712bae",
    "SecretID": "8b1247ef-d172-4f99-b050-4dbe5d3df0cb",
    "Description": "Clone of Agent token for 'node1'",
    "Policies": [
        {
            "ID": "165d4317-e379-f732-ce70-86278c4558f7",
            "Name": "node1-write"
        },
        {
            "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
            "Name": "node-read"
        },
        {
            "ID": "93d2226b-2046-4db1-993b-c0581b5d2391",
            "Name": "service-read"
        }
    ],
    "Local": false,
    "CreateTime": "2018-10-24T12:25:06.921933-04:00",
    "Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
    "CreateIndex": 128,
    "ModifyIndex": 128
}

» Delete a Token

This endpoint deletes an ACL token.

Method Path Produces
DELETE /acl/token/:AccessorID 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

» Parameters

  • AccessorID (string: <required>) - Specifies the accessor ID of the ACL policy to delete. This is required and is specified as part of the URL path.

» Sample Request

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

» Sample Response

true

» List Tokens

This endpoint lists all the ACL tokens.

Method Path Produces
GET /acl/tokens 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

» Parameters

  • policy (string: "") - Filters the token list to those tokens that are linked with the specific policy ID.

» Sample Request

$ curl -X GET http://127.0.0.1:8500/v1/acl/tokens

» Sample Response

[
    {
        "AccessorID": "6a1253d2-1785-24fd-91c2-f8e78c745511",
        "Description": "Agent token for 'my-agent'",
        "Policies": [
            {
                "ID": "165d4317-e379-f732-ce70-86278c4558f7",
                "Name": "node1-write"
            },
            {
                "ID": "e359bd81-baca-903e-7e64-1ccd9fdc78f5",
                "Name": "node-read"
            }
        ],
        "Local": false,
        "CreateTime": "2018-10-24T12:25:06.921933-04:00",
        "Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
        "CreateIndex": 59,
        "ModifyIndex": 59
    },
    {
        "AccessorID": "00000000-0000-0000-0000-000000000002",
        "Description": "Anonymous Token",
        "Policies": null,
        "Local": false,
        "CreateTime": "0001-01-01T00:00:00Z",
        "Hash": "RNVFSWnfd5DUOuB8vplp+imivlIna3fKQVnkUHh21cA=",
        "CreateIndex": 5,
        "ModifyIndex": 5
    },
    {
        "AccessorID": "3328f9a6-433c-02d0-6649-7d07268dfec7",
        "Description": "Bootstrap Token (Global Management)",
        "Policies": [
            {
                "ID": "00000000-0000-0000-0000-000000000001",
                "Name": "global-management"
            }
        ],
        "Local": false,
        "CreateTime": "2018-10-24T11:42:02.6427-04:00",
        "Hash": "oyrov6+GFLjo/KZAfqgxF/X4J/3LX0435DOBy9V22I0=",
        "CreateIndex": 12,
        "ModifyIndex": 12
    }
]