---
layout: commands
page_title: 'Commands: ACL Token Update'
---

# Consul ACL Token Update

Command: `consul acl token update`

Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token/:AccessorID](/api-docs/acl/tokens#update-a-token)

The `acl token update` command will update a token. Some parts of the token like whether the
token is local to the datacenter cannot be changed.

The table below shows this command's [required ACLs](/api-docs#authentication). Configuration of
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
are not supported from commands, but may be from the corresponding HTTP endpoint.

| ACL Required |
| ------------ |
| `acl:write`  |

## Usage

Usage: `consul acl token update [options]`

#### Command 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-node-identities` - Merge the new node identities with the existing node
  identities.

- `-merge-policies` - Merge the new policies with the existing policies.

- `-merge-roles` - Merge the new roles with the existing roles.

- `-merge-service-identities` - Merge the new service identities with the existing service identities.

- `-meta` - Indicates that token metadata such as the content hash and Raft indices should be
  shown for each entry.

- `-node-identity=<value>` - Name of a node identity to use for this role. May
  be specified multiple times. Format is `NODENAME:DATACENTER`. Added in Consul
  1.8.1.

- `-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.

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

- `-role-name=<value>` - Name of a role to use for this token. May be specified multiple times.

- `-service-identity=<value>` - Name of a service identity to use for this
  token. May be specified multiple times. Format is the `SERVICENAME` or
  `SERVICENAME:DATACENTER1,DATACENTER2,...`
- `-upgrade-legacy` - Add new polices to a legacy token replacing all existing
  rules. This will cause the legacy token to behave exactly like a new token
  but keep the same secret.

~> When upgrading a legacy token you must ensure that the new policy or policies
specified grant equivalent or appropriate access for the existing clients using
this token. You can find examples on how to use the parameter in the [legacy
token
migration](https://learn.hashicorp.com/consul/day-2-agent-authentication/migrate-acl-tokens)
guide.

- `-format={pretty|json}` - Command output format. The default value is `pretty`.

#### Enterprise Options

@include 'http_api_partition_options.mdx'

@include 'http_api_namespace_options.mdx'

#### API Options

@include 'http_api_options_client.mdx'

@include 'http_api_options_server.mdx'

## Examples

Update the anonymous token:

```shell-session
$ 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:

```shell-session
$ 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
```