Remote Access Onboarding

Generate short-lived onboarding tickets for operator-managed remote device enrollment.

When an operator needs to enroll a remote user's device (Sophon Desktop, Sophon Mobile, or a Sophon Node) without emailing credentials, Sophon's Remote Access Onboarding flow issues short-lived, revocable tickets that wrap the Gateway URL and pairing information into a single deep link.

The user receives a URL or sophon:// deep link, follows it on their device, and the device auto-configures — no manual server URL entry, no copy-paste secrets.

When to use this

Onboarding new employees — issue a ticket; they install the app and click the link; they're in.
Migrating a user's device — generate a ticket valid for 30 minutes, share, done.
Helping a user who fat-fingered the Gateway URL — regenerate a fresh ticket instead of walking them through config screens.
Bulk-enrolling devices from a ticketing system — the REST endpoint makes this scriptable.

The flow

Operator creates a ticket in the Dashboard (or via API / CLI).
Operator shares the resulting URL via email, chat, or QR code.
User opens the URL on their target device.
Device auto-configures — Gateway URL is set; the user lands on the login screen or pairing flow (for Nodes).
Ticket is consumed after first use and cannot be reused.

Creating a ticket

Dashboard

Operations → Remote Access → New Ticket. Fill in:

Target device type — Desktop / Mobile / Node
For user — which Sophon user this ticket belongs to (optional; if unset, any user can use it)
Label — internal reference
TTL — minutes until expiration (default: 15, max: 60)
Single-use — consume on first use (default: yes)

Click Generate. You get:

A ticket URL — https://<gateway>/onboarding?ticket=<opaque-token>
A deep link — sophon://connect?onboarding=<opaque-token> (works when the app is already installed)
A QR code that encodes the deep link — scan with Mobile to open directly

Copy, share, revoke when done.

CLI

sophon admin onboarding create --type Desktop --user <id> --ttl 30m --label "Onboard Jane"
sophon admin onboarding list
sophon admin onboarding revoke <ticket-id>

REST

POST /api/admin/onboarding
{
  "deviceType": "Mobile",
  "userId": "usr_abc",
  "ttlMinutes": 30,
  "singleUse": true,
  "label": "Onboard Jane"
}

Response includes the ticket token, the full URL, and the deep link.

What's in a ticket

A ticket encodes:

Gateway URL — the PublicBaseUrl configured in appsettings.json
Dashboard URL — the DashboardBaseUrl (may differ if Dashboard is hosted separately)
Device type — determines which flow to open
User ID (optional) — for single-user tickets, pre-fills the login identity
Node ID + pairing secret (Node-type tickets only) — skips the CLI pair step
Ticket ID — for revocation
Expiration — signed timestamp

The ticket itself is a JWT signed by the Gateway's host identity key. The token is opaque to the user.

Device-type flows

Desktop

User opens the ticket URL in a browser on their Mac / Windows / Linux machine.
If Sophon Desktop is installed, the sophon:// deep link launches it with Gateway URL pre-set.
If not installed, a friendly page offers the download with the Gateway URL encoded in the installer arguments — first-run skips the URL prompt.

Mobile

User scans the QR code or opens the deep link.
Sophon Mobile launches straight into the login screen with Gateway URL pre-set.
If Sophon Mobile isn't installed, the page redirects to the App Store / Play Store with a deferred deep link — first launch after install consumes the ticket.

Node

Administrator runs the CLI with --onboarding-ticket <token> instead of --node-id / --secret:
```
sophon-node pair --onboarding-ticket <token>
```
The CLI unpacks the ticket, extracts the Gateway URL and pairing credentials, and performs the pair in one step.
The Dashboard shows a pending Node ready for approval.

Verification

Every onboarding ticket page shows:

Gateway name (human-readable)
Host ID — stable identifier per Gateway instance
Fingerprint — SHA-256 of the Gateway's TLS certificate

The user can verify these match what the operator told them out-of-band. Mismatches indicate a phishing attempt — don't proceed.

Verify via CLI:

sophon config fingerprint
# Host ID:     0x8f4c2a1b...
# TLS SHA-256: 47:89:ab:cd:...
# Gateway:     https://gw.example.com

Revocation

Tickets can be revoked at any time before consumption:

Operations → Remote Access → Active Tickets → Revoke. Or:

sophon admin onboarding revoke <ticket-id>

A revoked ticket fails on use with a clear error. The failed attempt is audited so the operator knows someone tried to use a revoked ticket.

Audit trail

Every ticket action is audited:

onboarding.created — operator, ticket ID, target user, TTL
onboarding.used — user, device, IP, time
onboarding.revoked — operator, ticket ID, reason
onboarding.failed — failed attempt (expired / revoked / already-used)

Configuration

{
  "Sophon": {
    "RemoteAccess": {
      "Enabled": true,
      "PublicBaseUrl": "https://gw.example.com",
      "DashboardBaseUrl": "https://app.example.com",
      "DefaultTicketTtlMinutes": 15,
      "MaxTicketTtlMinutes": 60,
      "AllowMultiUse": false
    }
  }
}

PublicBaseUrl must be a URL the end user's device can actually reach. If your Gateway is behind a reverse proxy or CDN, PublicBaseUrl is the public URL, not the internal one.

Security considerations

Expiration is enforced server-side — no amount of clock manipulation on the device side extends a ticket.
Single-use by default — if shared publicly, a ticket is consumed by the first person to open it; subsequent uses fail.
Revocable — even if a ticket leaks, an operator can kill it before use.
Host identity verification — fingerprint display prevents MITM attacks via spoofed Gateways.
Signed by host identity key — ticket content is tamper-evident.
Audit trail — every issuance, use, and revocation is logged.

Where to go next

Install & Pair a Sophon Node — the normal pair flow that onboarding tickets accelerate
Desktop App — how tickets pre-configure the app
Mobile App — deep-link behavior on iOS / Android

Remote Access Onboarding

On this page