Get a token for an app's window

POST

/apps/{id}/window

const url = 'http://127.0.0.1:7700/api/apps/example/window';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

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/apps/example/window \
  --header 'Authorization: Bearer <token>'

The portal calls this to open an app’s page. The box’s own screen or a paired device may call it, and an auditor too, since it changes nothing. It returns a token that lasts 12 hours, or until the device that opened it is removed. Open the page at /t/<app>/?access_token=<token>. The box adds a script at the top of each HTML page that puts the token on the page’s own fetch calls. A request the browser makes by itself (a module script, an image) carries no header, so add location.search to its address.

The page runs sandboxed with no origin of its own, so it can neither use the box’s screen nor read the opener’s token. The window token reaches only:

the app’s own routes, /t/<app> and everything under it, as whoever opened the window (the x-box-caller header stays what it was)
GET /tasks and GET /tasks/{id}
GET /approvals
POST /approvals/{id} for a request of the app’s own tasks

Anything else is a 403 that says so. An approval of another app’s task comes back as 403 with needs: shell and the task’s id, and the portal opens that task’s window for a person to answer. An expired token, or one whose device was removed, is a 401. The box keeps at most 1000 open windows, and the oldest goes first.

Authorizations

deviceToken
accessToken

Parameters

Path Parameters

required

string

The app’s id, its folder name.

Example

example

Responses

200

The window’s token.

application/json

object

token

required

The letter w and 48 hexadecimal characters.

string

expiresAt

required

string format: date-time

Example

{
  "token": "w3f9a1c2e7b84d05a6c19e0b2f7d83a4c5e61b09d2f8a7c31",
  "expiresAt": "2026-10-24T21:12:03.000Z"
}

401

An outside request with no device token, or with one that is unknown or revoked.

application/json

object

error

required

What went wrong

string

Example

{
  "error": "pair this phone with this computer first"
}

404

The app is not installed or is off.

application/json

object

error

required

What went wrong

string

Example

{
  "error": "example is not on"
}