consul/website/content/docs/security/acl/tokens/create/create-a-snapshot-agent-token.mdx

---
layout: docs
page_title: Create tokens for snapshot agents
description: >-
  Learn how to create an ACL token for the Consul snapshot agent.
---

# Create a snapshot agent token

This topic describes how to create a token for the Consul snapshot agent.

<EnterpriseAlert />

## Introduction

The `consul snapshot agent` command starts a process that takes snapshots of the state of the Consul
servers and either saves them locally or pushes them to a remote storage service. Refer to [Consul Snapshot Agent](/consul/commands/snapshot/agent) for additional information.

## Requirements

Core ACL functionality is available in all versions of Consul.

### Requirements for the `agent` command

The [`agent`](/consul/commands/snapshot/agent) subcommand requires [Consul Enterprise](https://www.hashicorp.com/products/consul/). All other [`snapshot` subcommands](/consul/commands/snapshot) are available in the open source version of Consul.

### Snapshot agent ACL requirements

The Consul snapshot agent must present a token linked to policies that grant the following set of permissions.

* `acl:write`: Enables the agent read and snapshot ACL data
* `key:write`: Enables the agent to create a key in the Consul KV store that serves as a leader election lock when multiple snapshot agents are running in an environment
* `session:write`: Enables the agent to create sessions for the specified Consul node where it is running
* `service:write`: Enables the agent to register into the catalog

@include 'create-token-requirements.mdx'

## Create a token

To create a token for the snapshot agent, you must define a policy, register the policy with Consul, and link the policy to a token.

### Define a policy

You can send policy definitions as command line or API arguments or define them in an external HCL or JSON file. Refer to [ACL Rules](/consul/docs/security/acl/acl-rules) for details about all of the rules you can use in your policies.

The following example policy is defined in a file. The policy grants the appropriate permissions for a snapshot agent running on a node named `server-1234` to register into the catalog as the `consul-snapshot` service. It uses the key `consul-snapshot/lock` for a leader election lock.

<CodeTabs>

```hcl
acl = "write"
key "consul-snapshot/lock" {
  policy = "write"
}
session "server-1234" {
  policy = "write"
}
service "consul-snapshot" {
  policy = "write"
}
```

```json
{
  "acl": "write",
  "key": {
    "consul-snapshot/lock": [{
      "policy": "write"
    }]
  },
  "service": {
    "consul-snapshot": [{
      "policy": "write"
    }]
  },
  "session": {
    "server-1234": [{
      "policy": "write"
    }]
  }
}
```

</CodeTabs>

### Register the policy with Consul

After defining the policy, you can register the policy with Consul using the command line or API endpoint.

You can specify an admin partition and namespace when creating policies in Consul Enterprise. Policies are only valid in the specified scopes. You must create the policy for the snapshot agent in the `default` namespace in the `default` partition.

<Tabs>

<Tab heading="CLI" group="CLI">

Run the `consul acl policy create` command and specify the policy rules to create a policy. Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.

The following example registers a policy defined in `snapshot-agent.hcl`:

```shell-session
$ consul acl policy create -partition "default" -namespace "default" \
  -name snapshot-agent -rules @snapshot-agent.hcl \
  -description "Snapshot agent policy"
```

</Tab>

<Tab heading="API" group="API">

Send a PUT request to the `/acl/policy` endpoint and specify the policy rules in the request body to create a policy. Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.

The following example registers the policy defined in `snapshot-agent.hcl`. You must embed policy rules in the `Rules` field of the request body.

```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Name": "snapshot-agent",
  "Description": "Snapshot agent policy",
  "Partition": "default",
  "Namespace": "default",
  "Rules": "acl = \"write\"\nkey \"consul-snapshot/lock\" {\n  policy = \"write\"\n}\nsession \"server-1234\" {\n  policy = \"write\"\n}\nservice \"consul-snapshot\" {\n  policy = \"write\"\n}\n"
}'
```

</Tab>

</Tabs>

### Link the policy to a token

After registering the policies into Consul, you can create and link tokens using the Consul command line or API endpoint. You can also enable Consul to dynamically create tokens from trusted external systems using an [auth method](/consul/docs/security/acl/auth-methods).

You can specify an admin partition and namespace when creating tokens in Consul Enterprise. Tokens are only valid in the specified scopes. The snapshot agent token must be created in the `default` namespace in the `default` partition.

<Tabs>

<Tab heading="CLI" group="CLI">

Run the `consul acl token create` command and specify the policy name or ID to create a token linked to the policy. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.

The following command creates the ACL token linked to the policy `snapshot-agent`.

```shell-session
$ consul acl token create -partition "default" -namespace "default" \
    -description "Snapshot agent token" \
    -policy-name "snapshot-agent"
```

</Tab>

<Tab heading="API" group="API">

Send a PUT request to the `/acl/token` endpoint and specify the policy name or ID in the request to create an ACL token linked to the policy. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.

```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "snapshot-agent"
    }
  ],
  "Partition": "default",
  "Namespace": "default"
}'
```

</Tab>

</Tabs>