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

---
layout: docs
page_title: Create tokens for agent registration
description: >-
  Learn how to create ACL tokens that your Consul agents can present to Consul servers so that they can join the Consul cluster.
---

# Create an agent token

This topic describes how to create a token that you can use to register an agent into the catalog.

## Introduction

Consul agents must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to discover services and nodes in the catalog.

Specify the [`agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) token to the Consul agent so that it can present the token when it registers into the catalog.

### Node identities versus custom policies

You can create tokens linked to custom policies or to node identities. [Node identities](/consul/docs/security/acl#node-identities) are constructs in Consul that enable you to quickly grant permissions for a group of agents, rather than create similar policies for each agent.

We recommend using a node identity to grant permissions to the agent rather than creating a custom policy. This is because node identities automatically grant the node `node:write` and `service:read` permission.

Your organization may have requirements or processes for deploying services in a way that is inconsistent with service and node identities. In these cases, you can create custom policies and link them to tokens.

## Requirements

Core ACL functionality is available in all versions of Consul.

The agent token must be linked to policies that grant the following permissions:

* `node:write`: Enables the agent to update the catalog.
* `service:read`: Enables the agent to discover other services in the catalog

@include 'create-token-requirements.mdx'

## Node identity in Consul CE

Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens.

You can manually create 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 or node identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.

The following command creates an ACL token linked to a node identity for a node named `node1` in the datacenter `dc1`.

```shell-session
$ consul acl token create \
  -description "Agent token for node1" \
  -node-identity "node1:dc1"
```

</Tab>

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

Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.

The following example creates a token linked to a node identity named `node1`:

```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "NodeIdentities": [
    {
      "NodeName": "node1",
      "Datacenter": "dc1"
    }
  ]
}'
```

</Tab>

</Tabs>

## Node identity in Consul Enterprise

Refer to [Node identities](/consul/docs/security/acl#node-identities) for information about node identities that you can link to tokens.

You can manually create 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 or node identity to link to create a token. Refer to [Consul ACL Token Create](/consul/commands/acl/token/create) for details about the `consul acl token create` command.

You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in partition `ptn1` in datacenter `dc1`:

```shell-session
$ consul acl token create -partition "ptn1" \
  -description "Agent token for node1" \
  -node-identity "node1:dc1"
```

</Tab>

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

Send a PUT request to the `/acl/token` endpoint and specify a node identity in the request body to create a token linked to the node identity. An ACL token linked to a policy with permissions to use the API endpoint is required. Refer to [ACL Token HTTP API](/consul/api-docs/acl/tokens) for additional information about using the API endpoint.

You can specify an admin partition when creating a token in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register in the partition `ptn1` in datacenter `dc1`:

```shell-session
$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
  --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
  --data '{
  "NodeIdentities": [
    {
      "NodeName": "node1",
      "Datacenter": "dc1"
    }
  ],
  "Partition": "ptn1"
}'
```

</Tab>

</Tabs>

## Custom policy in Consul CE

When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog.

### 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 `write` permission for node `node1` so that the Consul agent can register into the catalog. It grants `read` permissions to discover services in the catalog.

<CodeTabs>

```hcl
node "node1" {
  policy = "write"
}
service_prefix "" {
  policy = "read"
}
```

```json
{
  "node": {
    "node1": [{
      "policy": "write"
    }]
  },
  "service_prefix": {
    "": [{
      "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. The following example registers a policy defined in `node1-register.hcl`:

```shell-session
$ consul acl policy create \
    -name "node1-register" -rules @node1-register.hcl \
    -description "Custom policy for node1" \
```

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

</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. The following example registers the policy defined in `node1-register.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": "node1-register",
  "Description": "Allow node1 to register into the catalog",
  "Rules": "node \"node1\" {\n  policy = \"write\"\n}\nservice_prefix \"\" {\n  policy = \"read\"\n}\n"
}'
```

Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.

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

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

```shell-session
$ consul acl token create \
    -description "Agent token for node1" \
    -policy-name "node1-register"
```

</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 an ACL token that the agent can use to register as node `node1` in the catalog:

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

</Tab>

</Tabs>



## Custom policy in Consul Enterprise

When you are unable to link tokens to a node identity, you can define policies, register them with Consul, and link the policies to tokens that enable nodes to register into the Consul catalog.

### 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 `write` permission for node `node1` in partition `ptn1` so that the Consul agent can register into the catalog. It grants `read` permissions to discover services in any namespace in the `ptn1` partition.

<CodeTabs>

```hcl
partition "ptn1" {
  node "node1" {
    policy = "write"
  }
  namespace_prefix "" {
    service_prefix "" {
      policy = "read"
    }
  }
}
```

```json
{
  "partition": {
    "ptn1": [{
      "namespace_prefix": {
        "": [{
          "service_prefix": {
            "": [{
              "policy": "read"
            }]
          }
        }]
      },
      "node": {
        "node1": [{
          "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. The following example registers a policy defined in `node1-register.hcl`:

```shell-session
$ consul acl policy create -partition "ptn1" \
  -name "node1-register" -rules @node1-register.hcl \
  -description "Custom policy for node1"
```

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

</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. The following example registers the policy defined in `node1-register.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": "node1-register",
  "Description": "Allow node1 to register into the catalog",
  "Partition": "ptn1",
  "Rules": "partition \"ptn1\" {\n  node \"node1\" {\n    policy = \"write\"\n  }\n  namespace_prefix \"\" {\n    service_prefix \"\" {\n      policy = \"read\"\n    }\n  }\n}\n"
}'
```

Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.

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

```shell-session
$ consul acl token create -partition "ptn1" \
    -description "Agent token for node1" \
    -policy-name "node1-register"
```

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

You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The following example creates an ACL token that the agent can use to register as the node `node1` in the partition `ptn1`:

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

</Tab>

</Tabs>

## Apply the token

Configure the Consul agent to present 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 [`acl.token.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) 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 = {
    agent = "<token>"
    ...
  }
  ...
}
```

### Apply the token with a command

Set the `agent` 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 acl set-agent-token agent <acl-token-secret-id>
```