Mobile Sessions API

The Sessions API enables two devices to share observation state in real time — for example, pairing a phone running the PWA with a laptop controlling a rotor, or letting two observers collaborate on the same tracking session. Each session is identified by a unique token and expires after 24 hours.

Once a session is created and joined, the paired devices communicate over a WebSocket relay at /ws/session/{token} (documented in the Tracking API).

Create Session

Creates a new pairing session and returns a unique token. The session expires 24 hours after creation.

POST /api/sessions

No request body is required.

Response (201 Created)

{
  "token": "a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2",
  "created_at": "2026-02-14T18:00:00Z",
  "expires_at": "2026-02-15T18:00:00Z",
  "is_paired": false
}

Field	Type	Description
token	string	URL-safe base64 token (43 characters) for identifying the session
created_at	datetime	When the session was created
expires_at	datetime	When the session will expire (24 hours from creation)
is_paired	boolean	Whether a second device has joined the session

Tip

The token is generated using secrets.token_urlsafe(32), producing a cryptographically random 43-character string. For verbal sharing between devices, consider displaying only a shortened prefix in the UI and using the full token for API calls.

---

Get Session

Retrieves the current state of an existing session.

GET /api/sessions/{token}

Parameter	Type	Description
token	string (path)	The session token

Response

{
  "token": "a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2",
  "created_at": "2026-02-14T18:00:00Z",
  "expires_at": "2026-02-15T18:00:00Z",
  "is_paired": true
}

Returns 404 if the session token does not exist. Returns 410 Gone if the session has expired.

Note

Expired sessions are not automatically deleted from the database. The API returns a 410 status to distinguish between a token that never existed (404) and one that has timed out.

---

Join Session

Joins an existing session from a second device. This sets is_paired to true and optionally records the joining device’s information.

POST /api/sessions/{token}/join

Parameter	Type	Description
token	string (path)	The session token to join

Request Body

{
  "device_info": "iPhone 15 Pro / Safari 19"
}

Field	Type	Required	Description
device_info	string or null	No	Free-form description of the joining device

Response

{
  "token": "a1B2c3D4e5F6g7H8i9J0k1L2m3N4o5P6q7R8s9T0u1V2",
  "created_at": "2026-02-14T18:00:00Z",
  "expires_at": "2026-02-15T18:00:00Z",
  "is_paired": true
}

Returns 404 if the session token does not exist. Returns 410 Gone if the session has expired.

Caution

Joining a session that is already paired will succeed and overwrite the stored device_info. The API does not enforce a two-device limit at the REST layer — the WebSocket relay handles multi-client coordination.

---

Delete Session

Ends a session immediately, removing it from the database. Any WebSocket connections on this session token will be closed by the relay.

DELETE /api/sessions/{token}

Parameter	Type	Description
token	string (path)	The session token to delete

Response

Returns 204 No Content on success. Returns 404 if the session token does not exist.

---

Session Lifecycle

A typical pairing flow works as follows:

1. Device A calls POST /api/sessions and receives a token.
2. Device A displays the token (or a QR code encoding it) for the second device.
3. Device B calls POST /api/sessions/{token}/join with optional device info.
4. Both devices open a WebSocket connection to /ws/session/{token} and begin exchanging real-time state (target coordinates, rotor position, tracking mode).
5. Either device can call DELETE /api/sessions/{token} to end the session, or it expires automatically after 24 hours.

Tip

Poll GET /api/sessions/{token} from Device A after displaying the token. When is_paired flips to true, Device A knows Device B has joined and can proceed to open the WebSocket relay.