Pair a phone

POST

/pair

curl --request POST \
  --url http://127.0.0.1:7700/api/pair \
  --header 'Content-Type: application/json' \
  --data '{ "code": "7f3a9c21", "name": "My phone" }'

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

A phone trades a pairing code for its own device token. The code stops working once used. Keep the token; the box does not show it again. Open without a token.

Request Body^required

Media typeapplication/json

object

code

required

The code from POST /pair/start.

string

name

A name for the phone, shown in the log when it answers. Default phone.

string

<= 40 characters

Example

{
  "code": "7f3a9c21",
  "name": "My phone"
}

Responses

200

The phone’s token.

Media typeapplication/json

object

token

required

The phone’s device token. Send it as Authorization: Bearer <token>.

string

device

required

object

id

string

name

string

box

required

object

id

string

name

string

Example ^generated

{
  "token": "example",
  "device": {
    "id": "example",
    "name": "example"
  },
  "box": {
    "id": "example",
    "name": "example"
  }
}

400

The code is wrong, used or expired.

Media typeapplication/json

object

error

required

What went wrong

string

Example

{
  "error": "bad or expired pairing code"
}