consul/website/source/docs/commands/acl/acl-token.html.md.erb

---
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 <subcommand> [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=<string>` - Create the token with this Accessor ID. It must be a UUID. If not
   specified one will be auto-generated

* `-description=<string>` - A description of the token.

* `-local` - Create this as a datacenter local token.

* `-policy-id=<value>` - ID of a policy to use for this token. May be specified multiple times.

* `-policy-name=<value>` - 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=<string>` - 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=<string>` - A description of the new cloned token.

* `-id=<string>` -  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=<string>` - 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=<string>` - A description of the token

* `-id=<string>` - 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=<value>` - ID of a policy to use for this token. May be specified multiple times.

* `-policy-name=<value>` - 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=<string>` - 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
```