pair_exchange

POST

/v1/pair/exchange

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

Remote listener only. Trades a one-time pairing code for a device token. Rate-limited per peer IP; every attempt counts.

Request Body^required

Media typeapplication/json

object

code

required

string

name

string | null

cookie

Browser flow: set HttpOnly session cookies instead of returning the token.

boolean

Example^generated

{
  "code": "example",
  "name": "example",
  "cookie": true
}

Responses

200

Media typeapplication/json

object

device

required

A paired remote device. The bearer token itself is never stored; only its SHA-256 digest is (see remote::hash_token).

object

id

required

string

name

required

string

scope

required

view (read-only) or decide (adds decision, cancel and test requests).

string

enabled

required

boolean

push

required

boolean

created_at

required

integer format: int64

last_seen

integer | null format: int64

token

Long-lived device token (hu_ + 64 hex). Omitted in the cookie flow.

string | null

host

This computer’s name (its hostname), so a device paired with several computers can tell them apart. Absent when unknown.

string | null

Example^generated

{
  "device": {
    "id": "example",
    "name": "example",
    "scope": "example",
    "enabled": true,
    "push": true,
    "created_at": 1,
    "last_seen": 1
  },
  "token": "example",
  "host": "example"
}

401

Invalid, used, or expired code

429

Rate limited