Skip to content
PhyStack

PhyStack Device Provisioning, Authentication, and Network Communication

Overview

Section titled “Overview”

This document describes how PhyStack devices provision themselves, authenticate, and communicate with backend services. The process includes initial provisioning using a serial number or time-limited provisioning code, retrieval of device credentials, and ongoing communication with backend services through proxy-based network connections.

Network Communication

Section titled “Network Communication”

  • Transport: All device network traffic is routed over the HTTP Proxy Protocol on port 443.

  • Provisioning Endpoint: During provisioning, devices always connect to portal-eu.phystack.com regardless of their intended data residency.

  • Post-Provisioning Endpoint: After provisioning, devices connect to the appropriate regional endpoint based on their tenant’s data residency:

    • portal-eu.phystack.com (Europe)
    • portal-au.phystack.com (Australia)
    • portal-uae.phystack.com (UAE)
    • Other regional endpoints as available

  • Secure Upstream Communication: Within this proxy tunnel, all traffic is relayed using HTTPS via an HTTPS CONNECT request to PhyStack backend services.

  • Device Identification: Devices are identified at the proxy by a device identifier.

This identifier is not treated as a secret since it is transmitted in clear text. :::

Provisioning Workflow

Section titled “Provisioning Workflow”

Step 1: Device Polling for Provisioning

Section titled “Step 1: Device Polling for Provisioning”
  • A new device polls the backend using its serial number.
  • The device requests its credentials (device ID and device secret).
  • Every 5 minutes, the device also requests a 6-character provisioning code, valid for 5 minutes.

Step 2: Console Authorization

Section titled “Step 2: Console Authorization”
  • A user enters either the serial number or the provisioning code into the PhyStack Console (web management UI).
  • This action unlocks the device for provisioning.

Step 3: Credential Assignment

Section titled “Step 3: Credential Assignment”

  • On the next polling request using the valid serial number or time-limited code, the backend responds with:

    • Device ID
    • Device Secret

  • This can occur only once.

  • Any subsequent request using the same serial number or provisioning code will fail.

Post-Provisioning Communication

Section titled “Post-Provisioning Communication”

  • Once provisioned, the device uses its credentials to establish a WSS (WebSocket Secure) connection to the PhyStack Phyhub backend.

  • The device connects to the appropriate regional portal endpoint based on its tenant’s data residency (e.g., portal-au.phystack.com for Australian tenants).

  • Over this channel, the device can:

    • Retrieve its device twin
    • Report status updates
    • Receive updated configuration
                ┌─────────────────────────┐
                │   PhyStack Console (UI) │
                │ (enter SN or prov. code)│
                └────────────┬────────────┘
                             │
                             │
                  ┌──────────▼───────────┐
                  │    Backend Services  │
                  │ (Provisioning + Hub) │
                  └──────────┬───────────┘
                             │
            ┌────────────────┴──────────────────┐
            │                                   │
  ┌─────────▼───────────┐             ┌─────────▼───────────┐
  │   Provisioning API  │             │     Phyhub (WSS)    │
  │ - Serial number     │             │ - Device twin       │
  │ - Provisioning code │             │ - Status updates    │
  │ - Device ID/Secret  │             │ - Config updates    │
  └─────────┬───────────┘             └─────────┬───────────┘
            │                                   │
            │                                   │
    ┌───────▼────────┐                  ┌───────▼─────────┐
    │    Device      │                  │  Device (post-  │
    │  (pre-prov.)   │                  │  provisioning)  │
    │ - SN polling   │                  │ - WSS connect   │
    │ - Prov. code   │                  │ - Twin sync     │
    └────────────────┘                  └─────────────────┘




        ┌─────────────────────────────────────────┐
        │ Network Path:                           │
        │ Provisioning: Device → HTTP Proxy       │
        │ (443) → portal-eu.phystack.com → HTTPS  │
        │                                         │
        │ Post-Provisioning: Device → HTTP Proxy  │
        │ (443) → portal-{region}.phystack.com →  │
        │ HTTPS (based on tenant data residency)  │
        └─────────────────────────────────────────┘

Key Points

Section titled “Key Points”
  • Proxy-based design ensures all traffic is funneled through a controlled endpoint.
  • Centralized provisioning uses portal-eu.phystack.com for all initial device provisioning regardless of target region.
  • Regional communication routes post-provisioning traffic to the appropriate regional endpoint based on tenant data residency.
  • Serial numbers and provisioning codes are temporary identifiers for bootstrapping.
  • Credentials (Device ID & Secret) are assigned once and then used for secure WSS communication.
  • One-time provisioning ensures that credentials cannot be reissued with the same identifiers.