Desktop Publishing Relay

The SCPress Desktop workspace runs a local SCPress installation and connects it to a hosted SCPress relay. It supports approved desktop connections, settings publishing, file transfer in both directions, and local page snapshots. Hosted relay connections should use HTTPS.

Endpoint location

The administrator installs SCPress Online Relay.zip in the SCPress installation directory. It includes the scpress-relay endpoint folder. The endpoint is:

https://host.example/path/to/scpress/scpress-relay/

The desktop accepts either the site URL (for example, https://host.example/path/to/scpress) or the relay URL. It resolves a site URL to {baseUrl}/scpress-relay/index.php and a relay-folder URL to {baseUrl}/index.php.

Before pairing, the client can check that the relay endpoint is reachable. This read-only health check does not require pairing or an active license:

{"action":"ping"}

The successful response includes protocol_version. Actions other than ping require an active eligible license or the documented personal, superadmin-authorized, or host-whitelisted pairing path.

One-time site key

The site administrator generates a one-time key from Admin → Relay & Desktop. The site stores only the SHA-256 hash and expiry in its own database; its local relay endpoint reads that record when the desktop connects. The plaintext key is displayed once, expires after 15 minutes, and is consumed by the first successful connection. Generating another key replaces the previous one.

POST {baseUrl}/index.php
Content-Type: application/json

{"action":"pair","pairing_code":"<one-time-key>","client_id":"<32-character-device-id>","client_name":"SCPress Desktop"}

On success, the site relay stores a site-prefixed token hash for that desktop and returns the token. The desktop stores a separate connection for each relay URL. The site administrator can revoke each desktop independently.

Older desktop builds can still use the request-and-approve flow. The request expires after 10 minutes and can be approved or rejected by the site's administrator.

The private SCPress Desktop package can connect automatically to its configured personal site. Connecting to another site uses the site's one-time key flow above.

Authenticated requests

Send the token as a bearer credential:

Authorization: Bearer <token>
Content-Type: application/json

All API calls use POST JSON. CORS allows the desktop app to make credentialed-by-header requests; cookies are not used. Every request rechecks the server's active Pro entitlement.

Inspect the connection

{"action":"inspect"}

Returns the site name/version and capabilities. The relay supports safe site options and design settings. Content, plugins, and themes are unsupported.

Preview a design update

{"action":"preview","design_settings":{"layout_gap":16,"primary_light":"#4f46e5"}}

The site_settings object contains design_settings and a map of transferable options exported by the local SCPress workspace. The server sanitizes design values and excludes credential-like values and reserved relay keys. It stores a single 10-minute preview and returns stage_id plus changed setting names. A new preview replaces the previous staged preview. The legacy design_settings field is also accepted.

The desktop client must show the returned changed setting names and wait for the user to choose Publish. Do not automatically publish after Preview. The deploy request is rejected unless confirm_publish is explicitly true.

Publish the preview

{"action":"deploy","stage_id":"<stage-id>","confirm_publish":true}

The relay creates a rollback snapshot of the current design and any site options being changed, then saves the staged settings. The response includes a backup_id for rollback. Each preview is single-use.

Roll back

{"action":"rollback","backup_id":"<backup-id>"}

Up to ten prior design snapshots are retained; each can be used once. The desktop client should offer rollback after a successful publish.

Error responses

Errors are JSON objects with an error string and appropriate HTTP status. 401 indicates an unavailable or invalid pairing/access credential, 402 indicates that desktop publishing is unavailable for the site or connection, and 413 indicates a request or file transfer exceeded the configured size limit. A 503 response means the relay cannot find a readable SCPress configuration beside the core files.

Scope and security

Files Transfer browses the local site's directory tree and sends selected files or folders to matching paths online. Missing destination files and parent folders are created as needed. Selected files can also be copied to the online site's Downloads folder.

Quick Upload & Inbox sends standalone files from the computer to the online uploads location and routes recognized plugin or theme ZIPs to their matching existing folders. Plugin ZIP uploads replace files; they do not activate a new plugin, and theme uploads do not switch the active theme. Files sent from the online site are queued for the local site's Downloads folder with their relative paths preserved; the desktop can refresh its inbox to receive them.

Files waiting for Desktop are staged under the site's protected sc-content/data/desktop-relay-transfers/ directory, outside the public scpress-relay/ endpoint folder. The desktop acknowledges a file after saving it locally, which removes the staged transfer copy. Administrators can also remove queued files from the Relay page.

The local Desktop Relay page can open a requested page address in a new browser tab for live scrolling and navigation, while keeping the relay page open. It can also capture the page in a separate background Chrome or Edge browser, preview the still image, and save it under local Downloads/snapshots/ without taking over the user's current browser window. Site settings continue to use preview, explicit publish confirmation, and rollback.