> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pair a channel

> Use a pairing code to bind an Identity and Template to a Channel message scope.

`POST /api/v1/forward/channel_pairings`

Only applicable to Channels with `identity_resolution.mode=pairing`.

## Headers

| Header            | Required | Description                                               |
| ----------------- | -------- | --------------------------------------------------------- |
| `Authorization`   | Yes      | `Bearer <PAT>`                                            |
| `Content-Type`    | Yes      | `application/json`                                        |
| `Idempotency-Key` | No       | Client-generated unique idempotency key for safe retries. |

## Body parameters

| Parameter     | Type   | Required | Description                                            |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| `code`        | string | Yes      | 6-digit pairing code displayed in the Channel message. |
| `identity_id` | string | Yes      | Forward Identity ID to bind.                           |
| `template_id` | string | Yes      | Forward Template ID to bind.                           |

## Example request

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/channel_pairings' \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pairing-K7MP92" \
  -d '{
    "code": "K7MP92",
    "identity_id": "idn_019eabc123",
    "template_id": "tmpl_workspace_dev"
  }'
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "id": "pair_019eabc123",
  "type": "channel_pairing",
  "channel_id": "channel_019eabc123",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev",
  "status": "active",
  "paired_at": "2026-07-16T10:00:00Z"
}
```

## Response fields

| Field         | Type   | Description                      |
| ------------- | ------ | -------------------------------- |
| `id`          | string | Pairing ID, used when unpairing. |
| `type`        | string | Always `channel_pairing`.        |
| `channel_id`  | string | Channel ID.                      |
| `identity_id` | string | Bound Forward Identity ID.       |
| `template_id` | string | Bound Forward Template ID.       |
| `status`      | string | `active` on successful pairing.  |
| `paired_at`   | string | Pairing completion time.         |

## Error codes

| HTTP | Type                    | Trigger                                                                                  |
| ---- | ----------------------- | ---------------------------------------------------------------------------------------- |
| 400  | `invalid_request_error` | Pairing code format is invalid, does not exist, or the Channel is not in `pairing` mode. |
| 401  | `authentication_error`  | PAT is invalid or expired.                                                               |
| 404  | `not_found_error`       | Channel, Identity, or Template does not exist or is not visible to the caller.           |
| 409  | `conflict_error`        | Pairing code is already bound to a different Identity or Template.                       |

## Notes

* The server uses the `user_id` resolved from the PAT and the normalized `code` to locate the pending pairing record — the request does not need `channel_id`.
* Pairing codes are unique within a single user scope; the response returns the `channel_id` resolved by the server.
* Submitting the same code with the same Identity and Template is idempotent and returns the existing Pairing; any different binding value returns a conflict.
* A Channel is a transport connection; a Pairing is the actual execution context binding for that direct/room scope.
* After successful pairing, Forward best-efforts a success notification to the original conversation; notification failure does not roll back the Pairing.

## Related

<CardGroup cols={2}>
  <Card title="Create a channel" icon="plus" href="/cloud-agents/api/forward/channels/create" />

  <Card title="Unpair a channel" icon="link-slash" href="/cloud-agents/api/forward/channels/unpair-channel" />
</CardGroup>