Skip to content
Pluvira Docs v1.0.0-alpha.3

Device Pairing (RFC 8628)

Pluvira implements the OAuth 2.0 Device Authorization Grant (RFC 8628) protocol, enabling headless NAS and home server appliances to securely link with Pluvira Cloud without transmitting local IP addresses or exposing authentication tokens in browser query parameters.

  • Zero Plaintext Credentials: The local appliance never handles, stores, or transmits your email address or master passwords.
  • Crockford Base32 Identity: Upon successful pairing, Pluvira Cloud issues a unique, anonymous 12-character Crockford Base32 User ID (XXXX-XXXX-XXXX).
  • Instant Feature Unlock: Linking enables 1 manual Zero-Knowledge E2EE cloud backup snapshot (200 KB) and unlocks eligibility for the 14-day on-demand Pro trial.

2. Pairing Sequence Flow

[Local Pluvira WebUI]                [Pluvira Cloud]                [Customer Portal Browser]
         │                                  │                                   │
         │ 1. Click "Link Instance" ───────►│                                   │
         │ ◄── Returns user_code (600s) ────┤                                   │
         │     (e.g., WDJB-MJHT)            │                                   │
         │                                  │                                   │
         │                                  │ 2. Open /portal/pair?code=... ───►│
         │                                  │ 3. Authenticate & Authorize ◄─────┤
         │                                  │                                   │
         │ 4. Polls status every 5s ───────►│                                   │
         │ ◄── 200 OK: UID + License Token ─┤                                   │
  1. Initiate Pairing: In your local Pluvira WebUI, navigate to Settings → Cloud Account and click Link Instance.
  2. Retrieve User Code: The system generates an ephemeral 8-character pairing code (e.g. WDJB-MJHT) valid for 10 minutes.
  3. Authorize in Portal: Open the verification link on your smartphone or desktop browser (https://pluvira.com/portal/pair?code=WDJB-MJHT), review the connection details, and click Authorize.
  4. Secure Token Delivery: The local instance polls the pairing endpoint over HTTPS and securely ingests your anonymous Crockford UID and signed Ed25519 Pro license token.

3. M2M Device-Bound License Synchronization & Headless Vault Access

Upon pairing authorization, Pluvira Cloud issues a cryptographically secure 256-bit CSPRNG token (device_secret with prefix pds_...). This credential unlocks autonomous machine-to-machine capabilities:

  • Autonomous License Synchronization (POST /api/v1/pairing/sync-license): Background daemons refresh active Pro/Ultra license tokens directly over HTTPS without requiring user interaction or browser session cookies.
  • Headless E2EE Backup Vault Access (/api/v1/backup/*): Daemons authenticate using Authorization: Bearer pds_... and X-Device-Id headers to upload, download, and rotate encrypted configuration backups within the account’s tier quotas.
  • Device Revocation & Quota: Accounts support up to 5 active paired devices. Users can review connected hardware and revoke credentials with 1-click from the Customer Portal (POST /api/v1/portal/devices/{id}/revoke).

4. Managing Linked Instances

  • Self-Service Lease Purge: If an old server instance terminates abruptly, purge active IP leases with 1-click from the Customer Portal.
  • Unlink Instance: Disconnect any local instance at any time via Settings → Cloud Account → Unlink. Local playlists and configurations remain intact.