Relay & pairing

The shape of it

1. The box mints a join code: pingtower pair --email [email protected].
2. The app redeems the code against the box and gets a box-minted ptk_ key, plus a receipt.
3. pingtower.com confirms the receipt with the box, once, at GET /v1/pair/verify.
4. The app writes the relay credential to the box with PUT /v1/relay.
5. From then on, every project on the box has a webhook integration named “pingtower.com relay”. An escalation event goes out through it like any other webhook, and pingtower.com turns it into a push to the devices paired with that tenant.

The box never accepts a connection from pingtower.com beyond the one-time verify. Everything is outbound from the box, so it works from behind NAT as long as the app can reach the box’s URL when it pairs.

What the box needs

• A public URL the app can reach, with TLS in front. See Reverse proxy.
• To answer /v1/pair/verify from pingtower.com at pairing time.
• -secret-key set, so the relay credential is sealed at rest like any other integration secret.

Seats

Each paired account is a seat. POST /v1/pair/codes on the box, owner or admin, mints another code; ttl_seconds defaults to an hour and is capped at seven days. DELETE /v1/tenants/{tid}/pairings/{aid} on pingtower.com revokes a seat, which stops that person’s pages and nothing else.

Rotating the relay key

POST /v1/tenants/{tid}/relay-key on pingtower.com mints a new credential; write it to the box with PUT /v1/relay. Until you do, relayed pages fail and show in the relay integration’s delivery log on the box.

Without pairing

A self-hosted box needs none of this to alert. Webhook, Slack and Telegram deliver from the box directly. Pairing is only for the phone.