--- layout: "docs" page_title: "Commands: ACL Token Management" sidebar_current: "docs-commands-acl-token" --- # Consul ACL Tokens Command: `consul acl token` The `acl token` command is used to manage Consul's ACL tokens. There are subcommands for the individual operations that can be performed. * [`create`](#create) * [`clone`](#clone) * [`read`](#read) * [`update`](#update) * [`delete`](#delete) * [`list`](#list) ACL tokens are also accessible via the [HTTP API](/api/acl/acl.html). Usage: `consul acl token [options] [args]` -> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions. Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token` parameter. ## Identifying Tokens In several of the subcommands a token will have to be identified to be read, modified or deleted. Those subcommands support specifying the token by its ID using the `-id` parameter. The ID may be specified as a unique UUID prefix instead of the entire UUID. As long as it is unique it will be resolve to the full UUID and used. Additionally builtin token names will be accepted as the value of the `-id`. Builtin Tokens: | Token UUID | Token Name | | ------------------------------------ | ----------------- | | 00000000-0000-0000-0000-000000000002 | anonymous | ## Common Subcommand Options All of the `consul acl token` subcommands support the following options: <%= partial "docs/commands/http_api_options_client" %> <%= partial "docs/commands/http_api_options_server" %> ## `create` Command: `consul acl token create` This command creates new tokens. When creating a new token, policies may be linked using either the `-policy-id` or the `-policy-name options. When specifying policies by IDs you may use a unique prefix of the UUID as a shortcut for specifying the entire UUID. ### Usage #### Options * [Common Subcommand Options](#common-subcommand-options) * `-accessor=` - Create the token with this Accessor ID. It must be a UUID. If not specified one will be auto-generated * `-description=` - A description of the token. * `-local` - Create this as a datacenter local token. * `-policy-id=` - ID of a policy to use for this token. May be specified multiple times. * `-policy-name=` - Name of a policy to use for this token. May be specified multiple times. * `-meta` - Indicates that token metadata such as the content hash and raft indices should be shown for each entry. * `-secret=` - Create the token with this Secret ID. It must be a UUID. If not specified one will be auto-generated. **Note**: The SecretID is used to authorize operations against Consul and should be generated from an appropriate cryptographic source. ### Examples Create a new token: ```sh $ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d SecretID: ec15675e-2999-d789-832e-8c4794daa8d7 Description: Read Nodes and Services Local: false Create Time: 2018-10-22 15:33:39.01789 -0400 EDT Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read ``` Create a new local token: ```sh $ consul acl token create -description "Read Nodes and Services" -policy-id 06acc965 -local AccessorID: 4fdf0ec8-d251-3865-079c-7247c974fc50 SecretID: 02143514-abf2-6c23-0aa1-ec2107e68f6b Description: Read Nodes and Services Local: true Create Time: 2018-10-22 15:34:19.330265 -0400 EDT Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read ``` Create a new policy and link with policies by name: ```sh $ consul acl token create -description "Super User" -policy-name global-management AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa SecretID: ada7f751-f654-8872-7f93-498e799158b6 Description: Super User Local: false Create Time: 2018-10-22 15:35:28.787003 -0400 EDT Policies: 00000000-0000-0000-0000-000000000001 - global-management ``` ## `clone` Command: `consul acl token clone` This command clones an existing token. ### Usage Usage: `consul acl token clone [options] #### Options * [Common Subcommand Options](#common-subcommand-options) * `-description=` - A description of the new cloned token. * `-id=` - The Accessor ID of the token to clone. It may be specified as a unique ID prefix but will error if the prefix matches multiple token Accessor IDs. The special value of 'anonymous' may be provided instead of the anonymous tokens accessor ID ### Examples Clone a token: ```sh $ consul acl token clone -id 59f8 -description "Clone of Super User" Token cloned successfully. AccessorID: dcfa52ed-9288-b3ff-056d-255ef69d2d88 SecretID: 0005d17e-5bb2-7e8b-7bfa-15f2eee9ad14 Description: Clone of Super User Local: false Create Time: 2018-10-22 16:26:02.909096 -0400 EDT Policies: 00000000-0000-0000-0000-000000000001 - global-management ``` ## `read` Command: `consul acl token read` This command reads and displays a token details. ### Usage Usage: `consul acl token read [options] [args]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-id=` - The ID of the policy to read. It may be specified as a unique ID prefix but will error if the prefix matches multiple policy IDs. * `-meta` - Indicates that policy metadata such as the content hash and raft indices should be shown for each entry. * `-self` - Indicates that the current HTTP token should be read by secret ID instead of expecting a -id option. ### Examples Get token details: ```sh $ consul acl token read -id 986 AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d SecretID: ec15675e-2999-d789-832e-8c4794daa8d7 Description: Read Nodes and Services Local: false Create Time: 2018-10-22 15:33:39.01789 -0400 EDT Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read ``` Get token details using the token secret ID: ```sh $consul acl token read -self AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01 SecretID: 86cddfb9-2760-d947-358d-a2811156bf31 Description: Bootstrap Token (Global Management) Local: false Create Time: 2018-10-22 11:27:04.479026 -0400 EDT Policies: 00000000-0000-0000-0000-000000000001 - global-management ``` Get token details (Builtin Tokens) ```sh $ consul acl token read -id anonymous AccessorID: 00000000-0000-0000-0000-000000000002 SecretID: anonymous Description: Anonymous Token Local: false Create Time: 0001-01-01 00:00:00 +0000 UTC Policies: ``` ## `update` Command: `consul acl token update` This command will update a token. Some parts of the token like whether the token is local to the datacenter cannot be changed. ### Usage Usage: `consul acl token update [options]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-description=` - A description of the token * `-id=` - The Accessor ID of the token to read. It may be specified as a unique ID prefix but will error if the prefix matches multiple token Accessor IDs * `-merge-policies` - Merge the new policies with the existing policies * `-meta` - Indicates that token metadata such as the content hash and Raft indices should be shown for each entry. * `-policy-id=` - ID of a policy to use for this token. May be specified multiple times. * `-policy-name=` - Name of a policy to use for this token. May be specified multiple times. ### Examples Update the anonymous token: ```sh $ consul acl token update -id anonymous -policy-id 06acc Token updated successfully. AccessorID: 00000000-0000-0000-0000-000000000002 SecretID: anonymous Description: Anonymous Token Local: false Create Time: 0001-01-01 00:00:00 +0000 UTC Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read ``` Update a token description and take the policies from the existing token: ```sh $ consul acl token update -id 986193 -description "WonderToken" -merge-policies Token updated successfully. AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d SecretID: ec15675e-2999-d789-832e-8c4794daa8d7 Description: WonderToken Local: false Create Time: 2018-10-22 15:33:39.01789 -0400 EDT Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read ``` ## `delete` Command: `consul acl token delete` This command deletes a token. ### Usage Usage: `consul acl token delete [options]` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-id=` - The ID of the token to delete. It may be specified as a unique ID prefix but will error if the prefix matches multiple token IDs. ### Examples Delete a token: ```sh $ consul acl token delete -id 35b8 Token "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully ``` ## `list` Command: `consul acl token list` This command lists all tokens. By default it will not show metadata. ### Usage Usage: `consul acl token list` #### Options * [Common Subcommand Options](#common-subcommand-options) * `-meta` - Indicates that token metadata such as the content hash and Raft indices should be shown for each entry. ### Examples Default listing. ```sh $ consul acl token list AccessorID: 4d123dff-f460-73c3-02c4-8dd64d136e01 Description: Bootstrap Token (Global Management) Local: false Create Time: 2018-10-22 11:27:04.479026 -0400 EDT Legacy: false Policies: 00000000-0000-0000-0000-000000000001 - global-management AccessorID: 59f86a9b-d3b6-166c-32a0-be4ab3f94caa Description: Super User Local: false Create Time: 2018-10-22 15:35:28.787003 -0400 EDT Legacy: false Policies: 00000000-0000-0000-0000-000000000001 - global-management AccessorID: 00000000-0000-0000-0000-000000000002 Description: Anonymous Token Local: false Create Time: 0001-01-01 00:00:00 +0000 UTC Legacy: false Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read AccessorID: 986193b5-e2b5-eb26-6264-b524ea60cc6d Description: WonderToken Local: false Create Time: 2018-10-22 15:33:39.01789 -0400 EDT Legacy: false Policies: 06acc965-df4b-5a99-58cb-3250930c6324 - node-services-read ```