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.

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, consistency modes, agent caching, and required ACLs.

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. You should generally only choose one method or the other for linking your cluster, not both. If you do use both methods, they interact 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

{
  "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

$ 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

{
  "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, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`stale`, `consistent`	`none`	`operator:read`

Sample Request

$ curl --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   http://127.0.0.1:8500/api/hcp/v2/link/global

Sample Response

{
  "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, consistency modes, agent caching, and required ACLs.

Blocking Queries	Consistency Modes	Agent Caching	ACL Required
`NO`	`stale`, `consistent`	`none`	`operator:write`, `acl:write`

Sample Request

$ curl --request DELETE \
   --header "X-Consul-Token: 5cdcae6c-0cce-4210-86fe-5dff3b984a6e" \
   http://127.0.0.1:8500/api/hcp/v2/link/global