diff --git a/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx
new file mode 100644
index 000000000000..9736beb50d9e
--- /dev/null
+++ b/website/content/docs/security/acl/tokens/create/create-a-mesh-gateway-token.mdx
@@ -0,0 +1,508 @@
+---
+layout: docs
+page_title: Create a token for mesh gateway registration
+description: >-
+ Learn how to create ACL tokens that your mesh gateway can present to Consul servers so that they
+ can register with the Consul catalog.
+---
+
+# Create a mesh gateway token
+
+This topic describes how to create a token for a mesh gateway.
+
+## Introduction
+
+Mesh gateways enable service-to-service traffic between Consul datacenters or between Consul admin
+partitions. They also enable datacenters to be federated across wide area networks. Refer to [Mesh
+Gateways](/consul/docs/connect/gateways#mesh-gateways) for additional information.
+
+Gateways must present a token linked to policies that grant the appropriate set of permissions in
+order to be discoverable and to route to other services in a mesh.
+
+## Requiremements
+
+Core ACL functionality is available in all versions of Consul.
+
+The mesh gateway must present a token linked to a policy that grants the following permissions:
+
+* `mesh:write` to obtain leaf certificates for terminating TLS connections
+* `peering:read` for Consul cluster peering through mesh gateways. If you are not using cluster
+ peering or if the mesh gateway is not in the `default` partition, then you can omit the
+ `peering:read` permission.
+* `service:write` to allow the mesh gateway to register into the catalog
+* `service:read` for all services and `node:read` for all nodes in order to discover and route to services
+* `agent:read` to enable the `consul connect envoy` CLI command to automatically discover gRPC
+ settings from the Consul agent. If this command is not used to start the gateway or if the Consul
+ agent uses the default gRPC settings, then you can omit the `agent:read` permission.
+
+@include 'create-token-requirements.mdx'
+
+## Consul OSS
+
+To create a token for the mesh gateway, 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 register as a service named `mesh-gateway` and to operate as a mesh gateway.
+
+
+
+```hcl
+mesh = "write"
+peering = "read"
+service "mesh-gateway" {
+ policy = "write"
+}
+service_prefix "" {
+ policy = "read"
+}
+node_prefix "" {
+ policy = "read"
+}
+agent_prefix "" {
+ policy = "read"
+}
+```
+
+```json
+{
+ "mesh": "write",
+ "peering": "read",
+ "service": {
+ "mesh-gateway": [{
+ "policy": "write"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `mgw-register.hcl`:
+
+```shell-session
+$ consul acl policy create \
+ -name "mgw-register" -rules @mgw-register.hcl \
+ -description "Mesh gateway policy"
+```
+
+
+
+
+
+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 `mgw-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": "mgw-register",
+ "Description": "Mesh gateway policy",
+ "Rules": "mesh = \"write\"\npeering = \"read\"\nservice \"mesh-gateway\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nagent_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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 `mgw-register`.
+
+```shell-session
+$ consul acl token create \
+ -description "Mesh gateway token" \
+ -policy-name "mgw-register"
+```
+
+
+
+
+
+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": "mgw-register"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## Consul Enterprise in default partition
+
+To create a token for the mesh gateway, 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.
+
+You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace.
+
+The following example policy is defined in a file. The policy grants the appropriate permissions to register as a service named `mesh-gateway` and to operate as a mesh gateway in the default partition.
+
+
+
+```hcl
+mesh = "write"
+partition_prefix "" {
+ peering = "read"
+}
+partition "default" {
+ namespace "default" {
+ service "mesh-gateway" {
+ policy = "write"
+ }
+ agent_prefix "" {
+ policy = "read"
+ }
+ }
+ namespace_prefix "" {
+ node_prefix "" {
+ policy = "read"
+ }
+ service_prefix "" {
+ policy = "read"
+ }
+ }
+}
+```
+
+```json
+{
+ "mesh": "write",
+ "partition": {
+ "default": [{
+ "namespace": {
+ "default": [{
+ "service": {
+ "mesh-gateway": [{
+ "policy": "write"
+ }]
+ },
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ },
+ "namespace_prefix": {
+ "": [{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ }
+ }]
+ },
+ "partition_prefix": {
+ "": [{
+ "peering": "read"
+ }]
+ }
+}
+```
+
+
+
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `mgw-register.hcl`:
+
+You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. You must create the policy in the partition where the mesh gateway registers. The following example creates the policy in the `default` partition.
+
+```shell-session
+$ consul acl policy create -partition "default" \
+ -name mgw-register -rules @mgw-register.hcl \
+ -description "Mesh gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `mgw-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": "mgw-register",
+ "Description": "Mesh gateway policy",
+ "Partition": "default",
+ "Rules": "mesh = \"write\"\npeering = \"read\"\npartition_prefix \"\" {\n peering = \"read\"\n}\nnamespace \"default\" {\n service \"mesh-gateway\" {\n policy = \"write\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n}\nnamespace_prefix \"\" {\n node_prefix \"\" {\n \tpolicy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n}\n"
+}'
+```
+
+Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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.
+
+You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
+
+```shell-session
+$ consul acl token create -partition "default" \
+ -description "Mesh gateway token" \
+ -policy-name "mgw-register"
+```
+
+
+
+
+
+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 token must be created in the partition where the mesh gateway registers. The following example creates the token 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": "mgw-register"
+ }
+ ],
+ "Partition": "default"
+}'
+```
+
+
+
+
+
+## Consul Enterprise in non-default partition
+
+To create a token for the mesh gateway, 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.
+
+You can specify an admin partition and namespace when using Consul Enterprise. Mesh gateways must register into the `default` namespace. To register a mesh gateway in a non-default partition, create the ACL policy and token in the partition where the mesh gateway registers.
+
+The following example policy is defined in a file. The policy grants the appropriate permissions to register as a service named `mesh-gateway` and to operate as a mesh gateway in a non-default partition.
+
+
+
+```hcl
+mesh = "write"
+namespace "default" {
+ service "mesh-gateway" {
+ policy = "write"
+ }
+ agent_prefix "" {
+ policy = "read"
+ }
+}
+namespace_prefix "" {
+ node_prefix "" {
+ policy = "read"
+ }
+ service_prefix "" {
+ policy = "read"
+ }
+}
+```
+
+```json
+{
+ "mesh": "write",
+ "namespace": {
+ "default": [{
+ "service": {
+ "mesh-gateway": [{
+ "policy": "write"
+ }]
+ },
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ },
+ "namespace_prefix": {
+ "": [{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `mgw-register.hcl`:
+
+You can specify an admin partition when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition. You must create the policy in the partition where the mesh gateway registers. The following example creates the policy in the partition `ptn1`.
+
+```shell-session
+$ consul acl policy create -partition "ptn1" \
+ -name mgw-register -rules @mgw-register.hcl \
+ -description "Mesh gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `mgw-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": "mgw-register",
+ "Description": "Mesh gateway policy",
+ "Partition": "ptn1",
+ "Rules": "mesh = \"write\"\npeering = \"read\"\nnamespace \"default\" {\n service \"mesh-gateway\" {\n policy = \"write\"\n }\n agent_prefix \"\" {\n policy = \"read\"\n }\n}\nnamespace_prefix \"\" {\n node_prefix \"\" {\n \tpolicy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n}\n"
+}'
+```
+
+Refer to [ACL Policy HTTP API](/consul/api-docs/acl/policies) for additional information about using the API endpoint.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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.
+
+You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. The token must be created in the partition where the mesh gateway registers. The following example creates the token in the partition `ptn1`.
+
+```shell-session
+$ consul acl token create -partition "ptn1" \
+ -description "Mesh gateway token" \
+ -policy-name "mgw-register"
+```
+
+
+
+
+
+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 token must be created in the partition where the mesh gateway registers. The following example creates the token 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": "mgw-register"
+ }
+ ],
+ "Partition": "ptn1"
+}'
+```
+
+
+
+
diff --git a/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx
new file mode 100644
index 000000000000..125390b39830
--- /dev/null
+++ b/website/content/docs/security/acl/tokens/create/create-a-service-token.mdx
@@ -0,0 +1,416 @@
+---
+layout: docs
+page_title: Create tokens for service registration
+description: >-
+ Learn how to create ACL tokens that your services can present to Consul servers so that they can register with the Consul catalog.
+---
+
+# Create a service token
+
+This topic describes how to create a token that you can use to register a service and discover services in the Consul catalog. If you are using Consul service mesh, a sidecar proxy can use the token to discover and route traffic to other services.
+
+## Introduction
+
+Services must present a token linked to policies that grant the appropriate set of permissions in order to be discoverable or to interact with other services in a mesh.
+
+### Service identities versus custom policies
+
+You can create tokens linked to custom policies or to service identities. [Service identities](/consul/docs/security/acl#service-identities) are constructs in Consul that enable you to quickly grant permissions for a group of services, rather than creating similar policies for each service.
+
+We recommend using a service identity to grant permissions for service discovery and service mesh use cases rather than creating a custom policy. This is because service identities automatically grant the service and its sidecar proxy `service:write`, `service:read`, and `node:read`.
+
+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 service token must be linked to policies that grant the following permissions:
+
+* `service:write`: Enables the service to update the catalog. If service mesh is enabled, the service's sidecar proxy can also update the catalog. Note that this permission implicitly grants `intention:read` permission to sidecar proxies so that they can read and enforce intentions. Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for details.
+* `service:read`: Enables the service to learn about other services in the network. If service mesh is enabled, the service's sidecar proxy can also learn about other services in the network.
+* `node:read`: Enables the sidecar proxy to discover and route traffic to other services in the catalog if service mesh is enabled.
+
+@include 'create-token-requirements.mdx'
+
+## Service identity in Consul OSS
+
+Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service 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).
+
+
+
+
+
+Run the `consul acl token create` command and specify the policy or service 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 example creates an ACL token linked to a service identity for a service named `svc1`.
+
+```shell-session
+$ consul acl token create \
+ -description "Service token for svc1" \
+ -service-identity "svc1"
+```
+
+
+
+
+
+Send a PUT request to the `/acl/token` endpoint and specify a service identity in the request body to create a token linked to the service 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 service identity named `svc1`:
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+ --data '{
+ "ServiceIdentities": [
+ {
+ "ServiceName": "svc1"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## Service identity in Consul Enterprise
+
+Refer to [Service identities](/consul/docs/security/acl#service-identities) for information about creating service 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).
+
+
+
+
+
+Run the `consul acl token create` command and specify the policy or service 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, namespace, or both when creating tokens in Consul Enterprise. The token can only include permissions in the specified scope, if any. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`:
+
+```shell-session
+$ consul acl token create -partition "ptn1" -namespace "ns1" \
+ -description "Service token for svc1" \
+ -service-identity "svc1"
+```
+
+
+
+
+
+Send a PUT request to the `/acl/token` endpoint and specify a service identity in the request body to create a token linked to the service 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 and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`:
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+ --data '{
+ "ServiceIdentities": [
+ {
+ "ServiceName": "svc1"
+ }
+ ],
+ "Namespace": "ns1",
+ "Partition": "ptn1"
+}'
+```
+
+
+
+
+
+## Custom policy in Consul OSS
+
+When you are unable to link tokens to a service identity, you can define policies, register them with Consul, and link the policies to tokens that enable services 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 `svc1` service `write` permissions so that it can register into the catalog. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services.
+
+
+
+```hcl
+service "svc1" {
+ policy = "write"
+}
+service "svc1-sidecar-proxy" {
+ policy = "write"
+}
+service_prefix "" {
+ policy = "read"
+}
+node_prefix "" {
+ policy = "read"
+}
+```
+
+```json
+{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service": {
+ "svc1": [{
+ "policy": "write"
+ }],
+ "svc1-sidecar-proxy": [{
+ "policy": "write"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `svc1-register.hcl`:
+
+
+```shell-session
+$ consul acl policy create \
+ -name "svc1-register" -rules @svc1-register.hcl \
+ -description "Allow svc1 to register into the catalog"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl token create` command.
+
+
+
+
+
+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 `svc1-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": "svc1-register",
+ "Description": "Allow svc1 to register into the catalog",
+ "Rules": "service \"svc1\" {\n policy = \"write\"\n}\nservice \"svc1-sidecar-proxy\" {\n policy = \"write\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nnode_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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 commands create the ACL token linked to the policy `svc1-register`.
+
+```shell-session
+$ consul acl token create \
+ -description "Service token for svc1" \
+ -policy-name "svc1-register"
+```
+
+
+
+
+
+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 `svc1` service can use to register in the `ns1` namespaces of 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": "svc1-register"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## Custom policy in Consul Enterprise
+
+When you are unable to link tokens to a service identity, you can define policies, register them with Consul, and link the policies to tokens that enable services 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.
+
+You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes.
+
+The following example policy is defined in a file. The policy allows the `svc1` service to register in the `ns1` namespace of partition `ptn1`. For service mesh, the policy grants the `svc1-sidecar-proxy` service `write` permissions so that the sidecar proxy can register into the catalog. It grants service and node `read` permissions to discover and route to other services.
+
+
+
+```hcl
+partition "ptn1" {
+ namespace "ns1" {
+ service "svc1" {
+ policy = "write"
+ }
+ service "svc1-sidecar-proxy" {
+ policy = "write"
+ }
+ service_prefix "" {
+ policy = "read"
+ }
+ node_prefix "" {
+ policy = "read"
+ }
+ }
+}
+```
+
+```json
+{
+ "partition": {
+ "ptn1": [{
+ "namespace": {
+ "ns1": [{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service": {
+ "svc1": [{
+ "policy": "write"
+ }],
+ "svc1-sidecar-proxy": [{
+ "policy": "write"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `svc1-register.hcl`:
+
+
+```shell-session
+$ consul acl policy create -partition "ptn1" -namespace "ns1" \
+ -name "svc1-register" -rules @svc1-register.hcl \
+ -description "Custom policy for service svc1"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl token create` command.
+
+
+
+
+
+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 `svc1-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": "svc1-register",
+ "Description": "Allow svc1 to register into the catalog",
+ "Namespace": "ns1",
+ "Partition": "ptn1",
+ "Rules": "partition \"ptn1\" {\n namespace \"ns1\" {\n service \"svc1\" {\n policy = \"write\"\n }\n service \"svc1-sidecar-proxy\" {\n policy = \"write\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n node_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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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.
+
+You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. The following example creates an ACL token that the service can use to register in the `ns1` namespace of partition `ptn1`:
+
+The following commands create the ACL token linked to the policy `svc1-register`.
+
+```shell-session
+$ consul acl token create -partition "ptn1" -namespace "ns1" \
+ -description "Service token for svc1" \
+ -policy-name "svc1-register"
+```
+
+
+
+
+
+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 and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. The following example creates an ACL token that the service can use to register in the `ns1` namespace of 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": "svc1-register"
+ }
+ ],
+ "Namespace": "ns1",
+ "Partition": "ptn1"
+}'
+```
+
+
+
+
diff --git a/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx
new file mode 100644
index 000000000000..5ba304a9f84b
--- /dev/null
+++ b/website/content/docs/security/acl/tokens/create/create-a-terminating-gateway-token.mdx
@@ -0,0 +1,352 @@
+---
+layout: docs
+page_title: Create a token for terminating gateway registration
+description: >-
+ Learn how to create ACL tokens that your terminating gateway can present to Consul servers so that they can register with the Consul catalog.
+---
+
+# Create a terminating gateway token
+
+This topic describes how to create an ACL token that enables a terminating gateway to register with Consul.
+
+## Introduction
+
+Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to services and destinations outside the mesh.
+
+To learn how to configure terminating gateways, refer to the [Terminating Gateways](/consul/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation and the [Understand Terminating Gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways) tutorial.
+
+## Requirements
+
+Core ACL functionality is available in all versions of Consul.
+
+The terminating gateway token must be linked to policies that grant the appropriate set of permissions in order to be discoverable and to forward traffic out of the mesh. The following permissions are required:
+
+* `service:write` to allow the terminating gateway to register into the catalog
+* `service:write` for each service that it forwards traffic for
+* `node:read` for the nodes of each service that it forwards traffic for
+* `service:read` for all services and `node:read` for all nodes in order to discover and route to services
+* `agent:read` to enable the `consul connect envoy` CLI command to automatically discover gRPC settings from the Consul agent. If this command is not used to start the gateway or if the Consul agent uses the default gRPC settings, then you can omit the `agent:read` permission.
+
+@include 'create-token-requirements.mdx'
+
+## Consul OSS
+
+To create a token for the terminating gateway, 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 register as a service named `terminating-gateway` and to operate as a terminating gateway. For this example, the terminating gateway forwards traffic for two services named `external-service-1` and `external-service-2`. The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules.
+
+
+
+```hcl
+service "terminating-gateway" {
+ policy = "write"
+}
+service "external-service-1" {
+ policy = "write"
+}
+service "external-service-2" {
+ policy = "write"
+}
+node_prefix "" {
+ policy = "read"
+}
+agent_prefix "" {
+ policy = "read"
+}
+```
+
+```json
+{
+ "service": {
+ "terminating-gateway": [{
+ "policy": "write"
+ }],
+ "external-service-1": [{
+ "policy": "write"
+ }],
+ "external-service-2": [{
+ "policy": "write"
+ }]
+ },
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `tgw-register.hcl`:
+
+```shell-session
+$ consul acl policy create \
+ -name "tgw-register" -rules @tgw-register.hcl \
+ -description "Terminating gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `tgw-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": "tgw-register",
+ "Description": "Terminating gateway policy",
+ "Rules": "service \"terminating-gateway\" {\n policy = \"write\"\n}\nservice \"external-service-1\" {\n policy = \"write\"\n}\nservice \"external-service-2\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nagent_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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 `tgw-register`.
+
+```shell-session
+$ consul acl token create \
+ -description "Terminating gateway token" \
+ -policy-name "tgw-register"
+```
+
+
+
+
+
+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": "tgw-register"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## Consul Enterprise
+
+To create a token for the terminating gateway, 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.
+
+You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes.
+
+The following example policy is defined in a file. The policy grants the appropriate permissions for a terminating gateway to register as a service named `terminating-gateway` in namespace `ns1` in partition `ptn1`.
+
+For this example, the terminating gateway forwards traffic for the following two services:
+
+* `external-service-1` in the `default` namespace
+* `external-service-2` in the `ns1` namespace
+
+The policy examples include `service:write` permissions for these services. If you have additional services, your policy must include `service:write` permissions for the additional services to be included in the policy rules.
+
+The policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace.
+
+
+
+```hcl
+partition "ptn1" {
+ namespace "ns1" {
+ service "terminating-gateway" {
+ policy = "write"
+ }
+ node_prefix "" {
+ policy = "read"
+ }
+ service "external-service-2" {
+ policy = "write"
+ }
+ }
+ namespace "default" {
+ service "external-service-1" {
+ policy = "write"
+ }
+ node_prefix "" {
+ policy = "read"
+ }
+ agent_prefix "" {
+ policy = "read"
+ }
+ }
+}
+```
+
+```json
+{
+ "partition": {
+ "ptn1": [{
+ "namespace": {
+ "default": [{
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service": {
+ "external-service-1": [{
+ "policy": "write"
+ }]
+ }
+ }],
+ "ns1": [{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service": {
+ "external-service-2": [{
+ "policy": "write"
+ }],
+ "terminating-gateway": [{
+ "policy": "write"
+ }]
+ }
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+### 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. The policy is only valid in the specified admin partition and namespace. You must create the policy in the same partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the policy must be created in the `default` namespace. The following example creates the policy in the partition `ptn1` and `default` namespace because the example policy contains permissions for multiple namespaces.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `tgw-register.hcl`:
+
+```shell-session
+$ consul acl policy create -partition "ptn1" -namespace "default" \
+ -name "tgw-register" -rules @tgw-register.hcl \
+ -description "Terminating gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `tgw-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": "tgw-register",
+ "Description": "Terminating gateway policy",
+ "Partition": "ptn1",
+ "Namespace": "default",
+ "Rules": "partition \"ptn1\" {\n namespace \"ns1\" {\n service \"terminating-gateway\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service \"external-service-2\" {\n policy = \"write\"\n }\n }\n namespace \"default\" {\n service \"external-service-1\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n agent_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.
+
+
+
+
+
+### 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).
+
+You can specify an admin partition when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition. You must create the token in the partition where the terminating gateway is registered. If the terminating gateway requires permissions for multiple namespaces, then the token must be created in the `default` namespace. The following example creates the token in the `default` namespace in the `ptn1` partition because the example policy contains permissions for multiple namespaces.
+
+
+
+
+
+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" -namespace "default" \
+ -description "Terminating gateway token" \
+ -policy-name "tgw-register"
+```
+
+
+
+
+
+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": "tgw-register"
+ }
+ ],
+ "Partition": "ptn1",
+ "Namespace": "default"
+}'
+```
+
+
+
+
diff --git a/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx
new file mode 100644
index 000000000000..9c1e9019b5e7
--- /dev/null
+++ b/website/content/docs/security/acl/tokens/create/create-a-ui-token.mdx
@@ -0,0 +1,557 @@
+---
+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 a UI token
+
+This topic describes how to create a token that you can use to view resources in the Consul UI.
+
+## Introduction
+
+To navigate the Consul UI when ACLs are enabled, log into the UI with a token linked to policies that grant an appropriate set of permissions. The UI is unable to display resources that the token does not have permission to access.
+
+## Requirements
+
+Core ACL functionality is available in all versions of Consul.
+
+@include 'create-token-requirements.mdx'
+
+## View catalog in Consul OSS
+
+This section describes how to create a token that grants read-only access to the catalog. This token allows users to view the catalog without the ability to make changes. To create the ACL token, define a policy, create the policy, and then 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 allows users that login with the token to view all services and nodes in the catalog.
+
+
+
+```hcl
+service_prefix "" {
+ policy = "read"
+}
+node_prefix "" {
+ policy = "read"
+}
+```
+
+```json
+{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-catalog.hcl`.
+
+```shell-session
+$ consul acl policy create \
+ -name "ui-view-catalog" -rules @ui-view-catalog.hcl \
+ -description "Allow viewing the catalog"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `view-catalog.hcl`. You must embed the 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": "ui-view-catalog",
+ "Description": "Allow viewing the catalog",
+ "Rules": "service_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\n"
+}'
+```
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 `ui-view-catalog`.
+
+```shell-session
+$ consul acl token create \
+ -description "UI token to view the catalog" \
+ -policy-name "ui-view-catalog"
+```
+
+
+
+
+
+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 you can use to login to the UI and view 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": "ui-view-catalog"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## View catalog in Consul Enterprise
+
+This section describes how to create a token that grants read-only access to the catalog. This token allows users to view the catalog without the ability to make changes. To create the ACL token, define a policy, create the policy, and then 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 policy allows users that log in with the token to view services and nodes in the catalog in any partition and in any namespace. The `operator:read` permission is needed to list partitions. Without this permission, you can still view resources within a partition but cannot easily navigate to other partitions in the Consul UI.
+
+
+
+```hcl
+operator = "read"
+partition_prefix "" {
+ namespace_prefix "" {
+ service_prefix "" {
+ policy = "read"
+ }
+ node_prefix "" {
+ policy = "read"
+ }
+ }
+}
+```
+
+```json
+{
+ "partition_prefix": {
+ "": [{
+ "namespace_prefix": {
+ "": [{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-catalog.hcl`.
+
+You can specify an admin partition and namespace when registering policies in Consul Enterprise. Policies are only valid in the scopes specified during registration, but you can grant tokens registered in the `default` partition permission to access resources in a different partition than where the token was registered. Refer to the [admin partition documentation](/consul/docs/enterprise/admin-partitions#default-admin-partition) for additional information.
+
+The following example registers the policy in the `default` partition and the `default` namespace because the policy grants cross-partition and cross-namespace access.
+
+```shell-session
+$ consul acl policy create -partition "default" -namespace "default" \
+ -name "ui-view-catalog" -rules @ui-view-catalog.hcl \
+ -description "Allow viewing the catalog"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `view-catalog.hcl`. You must embed the 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": "ui-view-catalog",
+ "Description": "Allow viewing the catalog",
+ "Partition": "default",
+ "Namespace": "default",
+ "Rules": "partition_prefix \"\" {\n namespace_prefix \"\" {\n service_prefix \"\" {\n policy = \"read\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n }\n}\n"
+}'
+```
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 "UI token to view the catalog" \
+ -policy-name "ui-view-catalog"
+```
+
+
+
+
+
+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 and namespace when registering policies in Consul Enterprise. Policies are only valid in the scopes specified during registration, but you can grant tokens registered in the `default` partition permission to access resources in a different partition than where the token was registered. Refer to the [admin partition documentation](/consul/docs/enterprise/admin-partitions#default-admin-partition) for additional information.
+
+The following example registers the policy in the `default` partition and the `default` namespace because the policy grants cross-partition and cross-namespace access.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+ --data '{
+ "Policies": [
+ {
+ "Name": "ui-view-catalog"
+ }
+ ],
+ "Partition": "default",
+ "Namespace": "default"
+}'
+```
+
+
+
+
+
+## View all resources in Consul OSS
+
+This section describes how to create a token with read-only access to all resources in the Consul UI. This token allows users to view any resources without the ability to make changes. To create the ACL token, define a policy, create the policy, and then 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 allows users that log in with the token to view all services and nodes in the catalog, all objects in the key/value store, all intentions, and all ACL resources. The `acl:read` permission does not allow viewing the token secret ids.
+
+
+
+```hcl
+acl = "read"
+key_prefix "" {
+ policy = "read"
+}
+node_prefix "" {
+ policy = "read"
+}
+operator = "read"
+service_prefix "" {
+ policy = "read"
+ intentions = "read"
+}
+```
+
+```json
+{
+ "acl": "read",
+ "key_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "operator": "read",
+ "service_prefix": {
+ "": [{
+ "intentions": "read",
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-all.hcl`.
+
+```shell-session
+$ consul acl policy create \
+ -name "ui-view-all" -rules @ui-view-all.hcl \
+ -description "Allow viewing all resources"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `ui-view-all.hcl`. You must embed the 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": "ui-view-all",
+ "Description": "Allow viewing all resources",
+ "Rules": "acl = \"read\"\nkey_prefix \"\" {\n policy = \"read\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\noperator = \"read\"\nservice_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n}\n"
+}'
+```
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 `ui-view-all`.
+
+```shell-session
+$ consul acl token create \
+ -description "UI token to view all resources" \
+ -policy-name "ui-view-all"
+```
+
+
+
+
+
+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 you can use to login to the UI and view 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": "ui-view-all"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## View all resources in Consul Enterprise
+
+This section describes how to create a token with read-only access to all resources in the Consul UI. This token allows users to view any resources without the ability to make changes. To create the ACL token, define a policy, create the policy, and then 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 allows users that log in with the token to view all services and nodes in the catalog, all objects in the key-value store, all intentions, and all ACL resources in any namespace and any partition. The `acl:read` permission does not allow viewing the token secret ids.
+
+
+
+```hcl
+operator = "read"
+partition_prefix "" {
+ namespace_prefix "" {
+ acl = "read"
+ key_prefix "" {
+ policy = "read"
+ }
+ node_prefix "" {
+ policy = "read"
+ }
+ service_prefix "" {
+ policy = "read"
+ intentions = "read"
+ }
+ }
+}
+```
+
+```json
+{
+ "operator": "read",
+ "partition_prefix": {
+ "": [{
+ "namespace_prefix": {
+ "": [{
+ "acl": "read",
+ "key_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "intentions": "read",
+ "policy": "read"
+ }]
+ }
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `ui-view-all.hcl`.
+
+You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes. Because the policy grants cross-partition and cross-namespace access, the policy must be created in the `default` partition and the `default` namespace.
+
+```shell-session
+$ consul acl policy create -partition "default" -namespace "default" \
+ -name "ui-view-all" -rules @ui-view-all.hcl \
+ -description "Allow viewing all resources"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `ui-view-all.hcl`. You must embed the 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": "ui-view-all",
+ "Description": "Allow viewing all resources",
+ "Partition": "default",
+ "Namespace": "default",
+ "Rules": "operator = \"read\"\npartition_prefix \"\" {\n namespace_prefix \"\" {\n acl = \"read\"\n key_prefix \"\" {\n policy = \"read\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n intentions = \"read\"\n }\n }\n}\n"
+}'
+```
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 "UI token to view all resources" \
+ -policy-name "ui-view-all"
+```
+
+
+
+
+
+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 and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified scopes. Because the policy was created in the `default` partition and `default` namespace, the token must also be created in the `default` partition and `default` namespace.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+ --data '{
+ "Policies": [
+ {
+ "Name": "ui-view-all"
+ }
+ ],
+ "Partition": "default",
+ "Namespace": "default"
+}'
+```
+
+
+
+
diff --git a/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx
new file mode 100644
index 000000000000..598db91125f2
--- /dev/null
+++ b/website/content/docs/security/acl/tokens/create/create-an-agent-token.mdx
@@ -0,0 +1,407 @@
+---
+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 OSS
+
+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).
+
+
+
+
+
+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"
+```
+
+
+
+
+
+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"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## 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).
+
+
+
+
+
+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"
+```
+
+
+
+
+
+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"
+}'
+```
+
+
+
+
+
+## Custom policy in Consul OSS
+
+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.
+
+
+
+```hcl
+node "node1" {
+ policy = "write"
+}
+service_prefix "" {
+ policy = "read"
+}
+```
+
+```json
+{
+ "node": {
+ "node1": [{
+ "policy": "write"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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"
+```
+
+
+
+
+
+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"
+ }
+ ]
+}'
+```
+
+
+
+
+
+
+
+## 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.
+
+
+
+```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"
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policies, you can register them with Consul using the command line or API endpoint.
+
+
+
+
+
+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.
+
+
+
+
+
+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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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"
+```
+
+
+
+
+
+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"
+}'
+```
+
+
+
+
+
+## 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 = ""
+ ...
+ }
+ ...
+}
+```
+
+### 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
+```
diff --git a/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx
new file mode 100644
index 000000000000..65e01369966a
--- /dev/null
+++ b/website/content/docs/security/acl/tokens/create/create-an-ingress-gateway-token.mdx
@@ -0,0 +1,326 @@
+---
+layout: docs
+page_title: Create a token for ingress gateway registration
+description: >-
+ Learn how to create ACL tokens that your ingress gateway can present to Consul servers so that they can register with the Consul catalog.
+---
+
+# Create an ingress gateway token
+
+This topic describes how to create a token to enable an ingress gateway to register.
+
+## Introduction
+
+Gateways must present a token linked to policies that grant the appropriate set of permissions in order to register into the catalog and to route to other services in a mesh.
+
+## Requirements
+
+Core ACL functionality is available in all versions of Consul.
+
+The ingress gateway token must be linked to policies that grant the following permissions:
+
+* `service:write` to allow the ingress gateway to register into the catalog
+* `service:read` for all services and `node:read` for all nodes in order to discover and route to services
+* `agent:read` to enable the `consul connect envoy` CLI command to automatically discover gRPC settings from the Consul agent. If this command is not used to start the gateway or if the Consul agent uses the default gRPC settings, then you can omit the `agent:read` permission.
+
+@include 'create-token-requirements.mdx'
+
+## Consul OSS
+
+To create a token for the ingress gateway, 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 ingress gateway the appropriate permissions to register as a service named `ingress-gateway` and to operate as an ingress gateway.
+
+
+
+```hcl
+service "ingress-gateway" {
+ policy = "write"
+}
+node_prefix "" {
+ policy = "read"
+}
+service_prefix "" {
+ policy = "read"
+}
+agent_prefix "" {
+ policy = "read"
+}
+```
+
+```json
+{
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service": {
+ "ingress-gateway": [{
+ "policy": "write"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `igw-register.hcl`:
+
+```shell-session
+$ consul acl policy create \
+ -name "igw-register" -rules @igw-register.hcl \
+ -description "Ingress gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `igw-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": "igw-register",
+ "Description": "Ingress gateway policy",
+ "Rules": "service \"ingress-gateway\" {\n policy = \"write\"\n}\nnode_prefix \"\" {\n policy = \"read\"\n}\nservice_prefix \"\" {\n policy = \"read\"\n}\nagent_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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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 `igw-register`.
+
+```shell-session
+$ consul acl token create \
+ -description "Ingress gateway token" \
+ -policy-name "igw-register"
+```
+
+
+
+
+
+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": "igw-register"
+ }
+ ]
+}'
+```
+
+
+
+
+
+## Consul Enterprise
+
+To create a token for the ingress gateway, 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.
+
+You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified scopes.
+
+The following example policy is defined in a file. The policy allows an ingress gateway to register as a service named `ingress-gateway` in the `ptn1` partition and `ns1` namespace. The policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace.
+
+
+
+```hcl
+partition "ptn1" {
+ namespace "ns1" {
+ service "ingress-gateway" {
+ policy = "write"
+ }
+ node_prefix "" {
+ policy = "read"
+ }
+ service_prefix "" {
+ policy = "read"
+ }
+ }
+ namespace "default" {
+ agent_prefix "" {
+ policy = "read"
+ }
+ }
+}
+```
+
+```json
+{
+ "partition": {
+ "ptn1": [{
+ "namespace": {
+ "default": [{
+ "agent_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }],
+ "ns1": [{
+ "node_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ },
+ "service": {
+ "ingress-gateway": [{
+ "policy": "write"
+ }]
+ },
+ "service_prefix": {
+ "": [{
+ "policy": "read"
+ }]
+ }
+ }]
+ }
+ }]
+ }
+}
+```
+
+
+
+### Register the policy with Consul
+
+After defining the policy, you can register the policy with Consul using the command line or API endpoint.
+
+The following commands create the ACL policy and token.
+
+
+
+
+
+Run the `consul acl policy create` command and specify the policy rules to create a policy. The following example registers a policy defined in `igw-register.hcl`:
+
+You can specify an admin partition and namespace when creating policies in Consul Enterprise. The policy is only valid in the specified admin partition and namespace. The following example creates the policy in the `default` namespace in the `ptn1` partition. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace.
+
+```shell-session
+$ consul acl policy create -partition "ptn1" -namespace "default" \
+ -name "igw-register" -rules @igw-register.hcl \
+ -description "Ingress gateway policy"
+```
+
+Refer to [Consul ACL Policy Create](/consul/commands/acl/policy/create) for details about the `consul acl policy create` command.
+
+
+
+
+
+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 `igw-register.hcl`. You must embed policy rules in the `Rules` field of the request body.
+
+You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `ns1`. The example policy contains permissions for resources in multiple namespaces. You must create ACL policies that grant permissions for multiple namespaces in the `default` namespace.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/policy \
+ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+ --data '{
+ "Name": "igw-register",
+ "Description": "Ingress gateway policy",
+ "Partition": "ptn1",
+ "Namespace": "default",
+ "Rules": "partition \"ptn1\" {\n namespace \"ns1\" {\n service \"ingress-gateway\" {\n policy = \"write\"\n }\n node_prefix \"\" {\n policy = \"read\"\n }\n service_prefix \"\" {\n policy = \"read\"\n }\n }\n namespace \"default\" {\n agent_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.
+
+
+
+
+
+### 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).
+
+
+
+
+
+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.
+
+You can specify an admin partition and namespace when creating tokens in Consul Enterprise. The token is only valid in the specified admin partition and namespace. The following example creates the token in the partition `ptn1` and namespace `default`. The example policy contains permissions for resources in multiple namespaces. You must create ACL tokens linked to policies that grant permissions for multiple namespaces in the `default` namespace.
+
+```shell-session
+$ consul acl token create -partition "ptn1" -namespace "default" \
+ -description "Ingress gateway token" \
+ -policy-name "igw-register"
+```
+
+
+
+
+
+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. You must create the token in the partition where the ingress gateway is registered. The following example creates the token in the partition `ptn1` and namespace `default`.
+
+```shell-session
+$ curl --request PUT http://127.0.0.1:8500/v1/acl/token \
+ --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" \
+ --data '{
+ "Policies": [
+ {
+ "Name": "igw-register"
+ }
+ ],
+ "Partition": "ptn1",
+ "Namespace": "default"
+}'
+```
+
+
+
+
diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/tokens/index.mdx
similarity index 100%
rename from website/content/docs/security/acl/acl-tokens.mdx
rename to website/content/docs/security/acl/tokens/index.mdx
diff --git a/website/content/partials/create-token-auth-methods.mdx b/website/content/partials/create-token-auth-methods.mdx
new file mode 100644
index 000000000000..912870728503
--- /dev/null
+++ b/website/content/partials/create-token-auth-methods.mdx
@@ -0,0 +1,3 @@
+### Auth methods
+
+Auth methods are components that perform authentication against a trusted external party to authorize the creation of ACL tokens for use within the local datacenter. Refer to the [auth methods documentation](/consul/docs/security/acl/auth-methods) for details about how to leverage auth methods in your network.
diff --git a/website/content/partials/create-token-requirements.mdx b/website/content/partials/create-token-requirements.mdx
new file mode 100644
index 000000000000..bf4742719e8d
--- /dev/null
+++ b/website/content/partials/create-token-requirements.mdx
@@ -0,0 +1,22 @@
+### Authentication
+
+You must provide an ACL token linked to a policy with `acl:write` permissions to create and modify ACL tokens and policies using the CLI or API.
+
+You can provide the token manually using the `-token` option on the command line, but we recommend setting the `CONSUL_HTTP_TOKEN` environment variable to simplify your workflow:
+
+```shell-session
+$ export CONSUL_HTTP_TOKEN=
+```
+
+The Consul CLI automatically reads the `CONSUL_HTTP_TOKEN` environment variable so that you do not have to pass the token to every Consul CLI command.
+
+To authenticate calls to the Consul HTTP API, you must provide the token in the `X-Consul-Token` header for each call:
+
+```shell-session
+$ curl --header "X-Consul-Token: $CONSUL_HTTP_TOKEN" ...
+```
+
+To learn about alternative ways to authenticate, refer to the following documentation:
+
+* [CLI Authentication](/consul/commands#authentication)
+* [API Authentication](/consul/api-docs/api-structure#authentication)
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index d1424f688ea4..c3e2fd58b491 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -832,7 +832,41 @@
},
{
"title": "Tokens",
- "path": "security/acl/acl-tokens"
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "security/acl/tokens"
+ },
+ {
+ "title": "Create ACL Tokens",
+ "routes": [
+ {
+ "title": "Create a service token",
+ "path": "security/acl/tokens/create/create-a-service-token"
+ },
+ {
+ "title": "Create an agent token",
+ "path": "security/acl/tokens/create/create-an-agent-token"
+ },
+ {
+ "title": "Create a UI token",
+ "path": "security/acl/tokens/create/create-a-ui-token"
+ },
+ {
+ "title": "Create a mesh gateway token",
+ "path": "security/acl/tokens/create/create-a-mesh-gateway-token"
+ },
+ {
+ "title": "Create an ingress gateway token",
+ "path": "security/acl/tokens/create/create-an-ingress-gateway-token"
+ },
+ {
+ "title": "Create a terminating gateway token",
+ "path": "security/acl/tokens/create/create-a-terminating-gateway-token"
+ }
+ ]
+ }
+ ]
},
{
"title": "Policies",