---
layout: docs
page_title: Create tokens for service registration
description: Learn how to create an ACL token for Vault’s Consul storage backend.
---

# Create a token for Vault with Consul storage backend

This topic describes how to create a token for Vault’s Consul storage backend.

## Introduction

If you are using Vault to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/consul/docs/dynamic-app-config/kv) and the [Vault storage documentation](/vault/docs/configuration/storage) for additional information.

## Requirements

Core ACL functionality is available in all versions of Consul.

The Vault Consul storage backend must present a token linked to policies that grant the following permissions:

* `agent:read`: Provides KV visibility to all agents
* `key:write`: Enables writing to the KV store
* `service:write`: Enables the Vault service to register into the catalog
* `session:write`: Enables the agent to initialize a new session

@include 'create-token-requirements.mdx'

## Create a token linked to a policy

To create a token for Vault’s Consul storage backend, 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 to enable Vault to register as a service named `vault` and provides access to the `vault/` path in Consul's KV store.

<CodeTabs>

```hcl
agent_prefix "" {
  policy = "read"
}
key_prefix "vault/" {
  policy = "write"
}
service "vault" {
  policy = "write"
}
session_prefix "" {
  policy = "write"
}
```

```json
{
  "agent_prefix": {
    "": [{
      "policy": "read"
    }]
  },
  "key_prefix": {
    "vault/": [{
      "policy": "write"
    }]
  },
  "service": {
    "vault": [{
      "policy": "write"
    }]
  },
  "session_prefix": {
    "": [{
      "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.

<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 `vault-storage-backend.hcl`.

```shell-session
$ consul acl policy create -partition "default" -namespace "default" \
  -name vault-storage-backend -rules @vault-storage-backend.hcl \
  -description "Policy for the Vault Consul storage backend"
```

</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 `vault-storage-backend.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": "vault-storage-backend",
  "Description": "Policy for the Vault Consul storage backend",
  "Rules": "agent_prefix \"\" {\n  policy = \"read\"\n}\nkey_prefix \"vault/\" {\n  policy = \"write\"\n}\nservice \"vault\" {\n  policy = \"write\"\n}\nsession_prefix \"\" {\n  policy = \"write\"\n}\n"
}'
```

</Tab>

</Tabs>

### Link the policy to a token

After registering the policy 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).

<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 `vault-storage-backend`.

```shell-session
$ consul acl token create \
    -description "Token for the Vault Consul storage backend" \
    -policy-name "vault-storage-backend"
```

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

The following example creates the ACL token linked to the policy `vault-storage-backend`.

```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "Policies": [
    {
      "Name": "vault-storage-backend"
    }
  ]
}'
```

</Tab>

</Tabs>

