Make a pairing code

POST

/pair/start

const url = 'http://127.0.0.1:7700/api/pair/start';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"owner":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 http://127.0.0.1:7700/api/pair/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "owner": true }'

Owner only. A one-time code for the QR code on the box’s own screen. It works once and expires after 5 minutes. With owner: true, the phone that redeems it becomes an owner device; the flag is ignored from anyone who is not already the owner. When BOX_URL is set, url is absolute, so the QR code opens on a phone. POST /pair/new is the same route under its older name.

Authorizations

deviceToken
accessToken

Request Body

application/json

object

owner

Pair the phone as the owner’s.

boolean

Example

{
  "owner": true
}

Responses

200

The code.

application/json

object

code

required

Eight hexadecimal characters. Works once.

string

url

required

Where the phone pairs: <BOX_URL>/pair#<code>, or the path /pair#<code> when BOX_URL is unset.

string

expiresAt

required

Five minutes after it was made.

string format: date-time

box

required

object

string

name

string

Example

{
  "code": "7f3a9c21",
  "url": "http://box.local:7700/pair#7f3a9c21",
  "expiresAt": "2026-10-24T09:17:03.000Z",
  "box": {
    "id": "gurt-3f9a1c",
    "name": "gurt-3f9a1c"
  }
}

403

The owner’s route, called by someone who is not the box’s own screen or a device paired as the owner.

application/json

object

error

required

What went wrong

string

Example

{
  "error": "only the box's own screen or the owner's paired device can do this"
}

GurtOS is open source under the Apache License 2.0.Source code on GitHub.