Add Link API docs

.changelog/20308.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+docs: add Link API documentation
+```

website/content/api-docs/api-structure.mdx

@@ -41,7 +41,7 @@ $ curl \
 ```
 
 **Security Note:** Though you could pass the token through the `?token=` query parameter,
-this method is highly discouraged because the token can show up in access logs as part of the URL. 
+this method is highly discouraged because the token can show up in access logs as part of the URL.
 The `?token=` query parameter is deprecated and will be removed in a future Consul version.
 
 To learn more about the ACL system read the [documentation](/consul/docs/security/acl).
@@ -159,3 +159,8 @@ UUID-format identifiers generated by the Consul API use the
 These UUID-format strings are generated using high quality, purely random bytes.
 It is not intended to be RFC compliant, merely to use a well-understood string
 representation of a 128-bit value.
+
+## CORS HTTP Response Headers
+
+As of Consul 1.18, Consul adds an HTTP header `Access-Control-Expose-Headers: x-consul-default-acl-policy` to
+all responses in order to support linking self-managed Consul clusters to HCP Consul Central.

website/content/api-docs/hcp.mdx

@@ -0,0 +1,186 @@
+---
+layout: api
+page_title: HCP Linking HTTP API
+description: The Link resource allows for linking your cluster to HCP Consul Central.
+---
+
+# Link HTTP API
+
+-> **1.18.0+:** The Link API is available in Consul versions 1.18.0 and newer.
+
+-> **Note:**  Cloud linking must be enabled in order to use the Link API.
+
+## Establish or Update Link to HCP Consul Central
+
+This endpoint creates or updates a Link, which establishes a connection with HCP Consul Central.
+
+| Method | Path                          | Produces           |
+| ------ | ----------------------------- | ------------------ |
+| `PUT`  | `/api/hcp/v2/link/global`     | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                   |
+| ---------------- | ----------------- | ------------- | ------------------------------ |
+| `NO`             | `none`            | `none`        | `operator:write`, `acl:write`  |
+
+### JSON Request Body Schema
+
+- `data` `(object: <required>)`
+
+  - `resourceId` `(string: <required>)` - The ID of the HCP Consul Central cluster to link to. Has the format of:
+    `organization/<orgID>/project/<projectID>/hashicorp.consul.global-network-manager.cluster/<clusterName>`
+
+  - `clientId` `(string: <required>)` - The ID used to authenticate to HCP, which is returned as part of the HCP
+    Consul Central cluster creation. It can also be obtained by fetching the HCP Consul Central cluster secrets.
+
+  - `clientSecret` `(string: <required>)` - The secret used to authenticate to HCP, which is returned as part of the
+    HCP Consul Central cluster creation. It can also be obtained by fetching the HCP Consul Central cluster secrets.
+
+### Sample Payload
+
+```json
+{
+  "data": {
+    "resourceId": "organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster",
+    "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5",
+    "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs"
+  }
+}
+```
+
+### Sample Request
+
+```shell-session
+$ curl --request PUT \
+   --header "X-Consul-Token: 9cdjse6c-2dia-3720-81fe-5dae3k714a6e" \
+   --data @payload.json \
+   http://127.0.0.1:8500/api/hcp/v2/link/global
+```
+
+### Sample Response
+
+```json
+{
+  "data": {
+    "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5",
+    "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs",
+    "resourceId": "organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster"
+  },
+  "generation": "01HMHTHZND8VJDXHHJBKDR4TTA",
+  "id": {
+    "name": "global",
+    "tenancy": {
+      "peerName": "local"
+    },
+    "type": {
+      "group": "hcp",
+      "groupVersion": "v2",
+      "kind": "Link"
+    },
+    "uid": "01HMHTHZND8VJDXHHJBGY1KG0F"
+  },
+  "version": "60"
+}
+```
+
+### Link API vs. Configuration-based Linking
+
+The Link API described here is an alternative method to accomplish the same thing as [configuration-based linking](/consul/docs/agent/config/config-files#self-managed-hcp-parameters). You should generally only choose one method or the other for linking your cluster, not both. If you do use both methods, they interract in the following ways:
+
+* Values set in the configuration will take precedence over what was set in the API/CLI when Consul is started.
+* SMCC can only be unlinked by the API/CLI, regardless of if they were established via configuration or API/CLI.
+
+## Read Link
+
+This endpoint reads a Link so you can view information about your cluster's current linking status.
+
+| Method | Path                          | Produces           |
+| ------ | ----------------------------- | ------------------ |
+| `GET`  | `/api/hcp/v2/link/global`     | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required     |
+| ---------------- | ----------------- | ------------- | ---------------- |
+| `NO`             | `none`            | `none`        | `operator:read`  |
+
+### Sample Request
+
+```shell-session
+curl --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
+   http://127.0.0.1:8500/api/hcp/v2/link/global
+```
+
+### Sample Response
+```json
+{
+  "data": {
+    "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5",
+    "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs",
+    "resourceId": "organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster"
+  },
+  "generation": "01HMHTF4K5V27T91FMVHGFE87F",
+  "id": {
+    "name": "global",
+    "tenancy": {
+      "peerName": "local"
+    },
+    "type": {
+      "group": "hcp",
+      "groupVersion": "v2",
+      "kind": "Link"
+    },
+    "uid": "01HMHS7DJ9FEQH5XK1VD0W0536"
+  },
+  "status": {
+    "consul.io/hcp/link": {
+      "conditions": [
+        {
+          "message": "Successfully linked to cluster 'organization/c0bf7aac-7690-4905-a8aa-889df1510314/project/6e82a47b-79af-4920-ad42-c0f74421ab52/hashicorp.consul.global-network-manager.cluster/my-cluster'",
+          "reason": "SUCCESS",
+          "state": "STATE_TRUE",
+          "type": "linked"
+        }
+      ],
+      "observedGeneration": "01HMHS7DN1C417JXJF7DBVS79F",
+      "updatedAt": "2024-01-19T21:14:59.707744Z"
+    }
+  },
+  "version": "53"
+}
+```
+
+## Delete an HCP Link
+
+This endpoint deletes an HCP Link, which removes the cluster's connection with HCP Consul Central.
+
+| Method    | Path                          | Produces           |
+| --------- | ----------------------------- | ------------------ |
+| `DELETE`  | `/api/hcp/v2/link/global`     | `application/json` |
+
+The table below shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required                     |
+| ---------------- | ----------------- | ------------- | -------------------------------- |
+| `NO`             | `none`            | `none`        | `operator:write`, `acl:write`    |
+
+### Sample Request
+
+```shell-session
+curl --request DELETE \
+   --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
+   http://127.0.0.1:8500/api/hcp/v2/link/global
+```

website/data/api-docs-nav-data.json

@@ -131,6 +131,10 @@
     "title": "Events",
     "path": "event"
   },
+  {
+    "title": "HCP Consul Central Link",
+    "path": "hcp"
+  },
   {
     "title": "Health",
     "path": "health"