PhyGrid Device Provisioning, Authentication, and Network Communication

Overview

This document describes how PhyGrid 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

• 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.phygrid.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.phygrid.com (Europe)
  • portal-au.phygrid.com (Australia)
  • portal-uae.phygrid.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 PhyGrid 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

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

• A user enters either the serial number or the provisioning code into the PhyGrid Console (web management UI).
• This action unlocks the device for provisioning.

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

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

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

• Over this channel, the device can:

  • Retrieve its device twin
  • Report status updates
  • Receive updated configuration

                ┌─────────────────────────┐
                │   PhyGrid 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.phygrid.com → HTTPS   │
        │                                         │
        │ Post-Provisioning: Device → HTTP Proxy  │
        │ (443) → portal-{region}.phygrid.com →   │
        │ HTTPS (based on tenant data residency)  │
        └─────────────────────────────────────────┘

Key Points

• Proxy-based design ensures all traffic is funneled through a controlled endpoint.
• Centralized provisioning uses portal-eu.phygrid.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.