page_title: Create tokens for service registration
description: >-
Learn how to create ACL tokens that a server agent in a secondary datacenter can use for ACL token replication between WAN-federated datacenters.
---
# Create a replication token
This topic describes how to configure an ACL token for ACL replication between WAN-federated datacenters. If your Consul clusters are connected through peer connections, ACL replication is not required. To learn more about cluster peering, refer to the [comparison between WAN federation and cluster peering](/consul/docs/connect/cluster-peering#compared-with-wan-federation).
## Introduction
Consul agents must present a token linked to policies that grant the appropriate set of permissions.
Specify the [`replication`](/consul/docs/agent/config/config-files#acl_tokens_replication) token on each server in a non-primary datacenter. For hands-on instructions on how to configure ACL replication across datacenters, refer to the [ACL Replication for Multiple Datacenters](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters) tutorial.
## Requirements
Core ACL functionality is available in all versions of Consul.
For a Consul server agent with ACL replication enabled in a secondary datacenter, the token must be linked to a policy that grants the following permissions:
* `acl:write`: Enables replication of ACL resources
* `operator:write`: Enables replication of the proxy-defaults configuration entry and enables CA certification signing in the secondary datacenter
* `service:read` and `intention:read`: Enables replication of the service-defaults and intentions configuration entries
To create a token for ACL replication, 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 ACL replication.
<CodeTabs>
```hcl
acl = "write"
operator = "write"
service_prefix "" {
policy = "read"
intentions = "read"
}
```
```json
{
"acl": "write",
"operator": "write",
"service_prefix": {
"": [{
"intentions": "read",
"policy": "read"
}]
}
}
```
</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 `acl-replication.hcl`.
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 `acl-replication.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 \
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.
<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 `acl-replication`.
```shell-session
$ consul acl token create \
-description "ACL replication" \
-policy-name "acl-replication"
```
</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 `acl-replication`.
```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"Policies": [
{
"Name": "acl-replication"
}
]
}'
```
</Tab>
</Tabs>
## Replication token in Consul Enterprise
To create a token for ACL replication, 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 following example policy grants the appropriate permissions for ACL replication.
<CodeTabs>
```hcl
operator = "write"
service_prefix "" {
policy = "read"
intentions = "read"
}
namespace_prefix "" {
acl = "write"
service_prefix "" {
policy = "read"
intentions = "read"
}
}
```
```json
{
"namespace_prefix": {
"": [{
"acl": "write",
"service_prefix": {
"": [{
"intentions": "read",
"policy": "read"
}]
}
}]
},
"operator": "write",
"service_prefix": {
"": [{
"intentions": "read",
"policy": "read"
}]
}
}
```
</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, namespace, or both when registering policies in Consul Enterprise. Policies are only valid in the specified scopes. The policy for replication must be created in the `default` namespace and `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 `acl-replication.hcl`.
```shell-session
$ consul acl policy create -partition "default" -namespace "default" \
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 `acl-replication.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 \
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.
```shell-session
$ consul acl token create -partition "default" -namespace "default" \
-description "ACL replication" \
-policy-name "acl-replication"
```
</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 `acl-replication`.
```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
--header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
--data '{
"Policies": [
{
"Name": "acl-replication"
}
],
"Partition": "default",
"Namespace": "default"
}'
```
</Tab>
</Tabs>
## Apply the token
Configure the Consul agent with the token by either specifying the token in the agent configuration file or by using the `consul set-agent-token` command.
### Apply the token in a file
Specify the token in the [`replication`](/consul/docs/agent/config/config-files#acl_tokens_replication) field of the agent configuration file so that the agent can present it and register into the catalog on startup.
```hcl
acl = {
enabled = true
tokens = {
replication = "<token>"
...
}
...
}
```
### Apply the token with a command
Set the `replication` token using the [`consul set-agent-token`](/consul/commands/acl/set-agent-token) command. The following command configures a running Consul agent token with the specified token.
```shell-session
$ consul set-agent-token replication <acl-token-secret-id>
