API reference

Most developers interact with GetPassive through the console and the Node.js SDK. The endpoints below describe the flow that the SDK and console use. Console endpoints are authenticated by the gp_dev_session cookie set after magic-link verification.

SDK ↔ gateway handshake

The SDK opens a secure WebSocket connection to the gateway and sends a single JSON handshake line. After the handshake the connection is used to carry length-prefixed binary frames.

GET wss://sdk.getpassive.io/
Upgrade: websocket

First message after the WebSocket is open:

{
  "device_uuid": "f2c1c1a0-9f4e-4b9a-9a30-1d4c8a0b1c2e",
  "dev_api_key": "gp_pk_********************************",
  "client_version": "0.1.0",
  "public_ip": "203.0.113.42"
}

The gateway validates the developer API key, the app status, and the developer's consent confirmation before keeping the connection alive. After validation the SDK accepts inbound stream frames and proxies them through the local device.

Console magic-link sign-in

Send a sign-in link to an approved developer email. The endpoint is protected by Turnstile and a per-IP and per-email rate limit. Responses are deliberately generic so the endpoint does not reveal which emails are approved.

POST https://app.getpassive.io/api/magic-link
Content-Type: application/json

{ "email": "[email protected]" }

{ "ok": true, "message": "Check your email for a sign-in link." }

Console magic-link verify

The link in the email points at the verify endpoint. On success it sets a 30-day gp_dev_session cookie scoped to getpassive.io and returns the developer email.

GET https://app.getpassive.io/api/verify?token=<64-hex-token>

{ "ok": true, "email": "[email protected]", "expires_in": 2592000 }

List apps

GET https://app.getpassive.io/api/dev/apps
Cookie: gp_dev_session=<session>

Returns each app the developer owns along with the API key prefix, key status, recent device counts, and lifetime earnings.

Create an app

Creates an application and issues a developer API key in the response. The key is shown once and is the only credential the SDK needs. New keys start in test mode.

POST https://app.getpassive.io/api/dev/apps
Cookie: gp_dev_session=<session>
Content-Type: application/json

{
  "app_name": "Example Desktop App",
  "platform": "Windows desktop, Node 18 helper process",
  "monthly_active_users": "10k-50k",
  "disclosure_method": "Bundled clause in Terms and Conditions"
}

{ "ok": true, "app_id": 123, "api_key": "gp_pk_***" }

SDK init check

Optional probe for tooling that wants to validate a developer API key before starting the SDK. The gateway performs the same check during the handshake; calling this directly is only useful for build-time validation or local diagnostics.

POST https://app.getpassive.io/api/dev/sdk/init
Content-Type: application/json

{ "dev_api_key": "gp_pk_***" }

{
  "ok": true,
  "dev_id": "[email protected]",
  "app_id": 123,
  "app_name": "Example Desktop App",
  "key_mode": "test",
  "is_test": true,
  "livemode": false,
  "consent_flow_confirmed": true,
  "consent_flow_confirmed_at": "2026-05-30T12:00:00Z"
}

SDK remote config

The SDK can fetch a small remote configuration document, mostly used to pick the correct gateway URL and to honour a kill switch issued by the platform.

GET https://getpassive.io/api/sdk/config?api_key=gp_pk_***

{
  "gateway_url": "wss://sdk.getpassive.io/",
  "telemetry_interval_seconds": 30,
  "kill_switch": false,
  "min_sdk_version": "1.0.0",
  "consent_required": false
}

Key and app status

Last updated June 11, 2026