pair_create

POST

/v1/pair

const url = 'https://example.com/v1/pair';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"scope":"view","name":"example","relay":true}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/v1/pair \
  --header 'Content-Type: application/json' \
  --data '{ "scope": "view", "name": "example", "relay": true }'

Local only (unix socket or loopback bearer). Issues a one-time pairing code for handup pair. With relay: true, opens a fresh relay channel and returns a relay pairing link that carries the channel, the device’s relay credential, the daemon’s Noise public key, and the code.

Request Body^required

application/json

Local-only: create a pairing request (body for POST /v1/pair).

object

scope

One of:

null
string

null

Defaults to decide.

string

Allowed values: view decide submit

name

Device name; the pairing page may suggest one when empty.

string | null

relay

Pair through the end-to-end encrypted relay (remote.relay.url) instead of the remote listener.

boolean

Responses

200

application/json

object

code

required

One-time code (single use, expires after 2 minutes).

string

url

required

Pairing page URL; the code travels in the fragment so it never reaches server logs.

string

expires_at

required

Epoch milliseconds.

integer format: int64

scope

required

string

Allowed values: view decide submit

name

string | null

fingerprint

TLS leaf certificate SHA-256 fingerprint when the remote listener uses TLS.

string | null

mode

required

string

Example

{
  "scope": "view"
}

409

Remote access (or the relay) is off or has no reachable base URL

502

The relay refused or could not be reached

pair_create

Request Bodyrequired

Responses

200

Example

409

502

Request Body^required