---
title: "Begin pairing"
method: POST
path: "/v1/connections/{connection}/pair"
tags: ["Connections"]
---

# Begin pairing

`POST /v1/connections/{connection}/pair`

## Request

- Base URL: `https://www.chatrail.dev`
- URL: `https://www.chatrail.dev/v1/connections/{connection}/pair`
- Auth: HTTP bearer

Issues a short-lived, single-use grant. By default it holds a QR; with `{"method": "code", "phone": "+447700900123"}` it holds a pairing code instead, which the person enters under Linked devices → Link with phone number (encoding `pairing-code`). Either is fetched once with the grant id: each is a pairing credential, so whoever uses it links *their* device to the number.

## Path parameters

- `connection` string, required

## Request body

- object
  - `method` 'qr' | 'code'
  - `phone` string

## Response `200`

A grant id and its expiry.

## Other responses

- `409`: The connection cannot be paired from its current state.
- `503`: No transport is configured on this deployment.

---

[API](https://skmtc.dev/chatrail/apis/chatrail-api.md) · [All operations](https://skmtc.dev/chatrail/apis/chatrail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chatrail/apis/chatrail-api/revisions/acc5b88c6f59?raw)