Make a pairing code for a person

POST

/people/{id}/pair

curl --request POST \
  --url http://127.0.0.1:7700/api/people/example/pair \
  --header 'Authorization: Bearer <token>'

• On the box itself (the default listen address)
• From another device, with a paired device token, when BOX_LISTEN allows it

Preview. For an admin or the owner; only the owner pairs a phone as the owner. The code is redeemed with POST /pair, and every request with that device’s token is that person.

Authorizations

• deviceToken
• accessToken

Parameters

Path Parameters

id

required

string

Responses

200

The code.

Media typeapplication/json

object

code

required

Eight hexadecimal characters. Works once.

string

url

required

Opens the GurtOS web app (BOX_APP) with the code: <app>/pair#code=<code>&.... With remote access on, <app>/pair?box=<address>#<code>.

string

boxUrl

The box’s own pairing page, <address>/pair#<code>. There only when BOX_URL or remote access gives the box an address.

string

expiresAt

required

Five minutes after it was made.

string format: date-time

box

required

object

id

string

name

string

person

string

Example ^generated

{
  "code": "example",
  "url": "example",
  "boxUrl": "example",
  "expiresAt": "2026-04-15T12:00:00Z",
  "box": {
    "id": "example",
    "name": "example"
  },
  "person": "example"
}

403

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

Media typeapplication/json

object

error

required

What went wrong

string

Example

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

404

No person with this id.

Media typeapplication/json

object

error

required

What went wrong

string

Example ^generated

{
  "error": "example"
}