consul/website/content/api-docs/hcp-link.mdx

---
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:** This endpoint does not use the `/v1/` prefix.

The `/api/hcp/v2/link/global` endpoint allows you to link your Consul cluster to [HCP Consul Central](/hcp/docs/consul/concepts/consul-central).

## 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`             | `stale`, `consistent` | `none`        | `operator:write`, `acl:write`  |

### 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:

* When Consul is started, values set in the `cloud` configuration will take precedence over what was previously set by the API or CLI.
* Clusters can only be unlinked from HCP Consul Central by the API or CLI, regardless of if they were established via configuration, API, or CLI.

### 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"
}
```

## 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`             | `stale`, `consistent` | `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": {
    "accessLevel": "ACCESS_LEVEL_GLOBAL_READ_WRITE",
    "clientId": "3jz6zk2tlr802htzwquczlxlsrohlpm5",
    "clientSecret": "07ywcvaqmg1f8ko9eq4julep2tfglnv4o18rz3py9dik4ywox0ytoscycn39o4vs",
    "hcpClusterUrl": "https://portal.cloud.hashicorp.com/services/consul/clusters/self-managed/my-cluster?project_id=6e82a47b-79af-4920-ad42-c0f74421ab52",
    "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 Link

This endpoint deletes a 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`             |  `stale`, `consistent` | `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
```