JunctionRelay ESP32 Token Management System¶

This documentation explains how the JunctionRelay ESP32 client maintains secure, long-term connectivity to the cloud platform through an advanced token management system.

🔑 Token Architecture¶

The system uses a two-tier token approach for maximum security and reliability:

Primary JWT Token¶

Purpose: Authenticates API requests (health reports, sensor data)
Lifetime: 8 hours (production) / 6 minutes (test mode)
Usage: Short-lived, frequently refreshed for security

Refresh Token¶

Purpose: Obtains new JWT tokens without re-registration
Lifetime: 7 days (production) / 18 minutes (test mode)
Usage: Long-lived, rotated before expiry

🔄 Automatic Token Management¶

The ESP32 client automatically handles the complete token lifecycle:

JWT Token Refresh¶

Every 1 hour OR when token expires in <5 minutes:
├── Send refresh request with current refresh token
├── Receive new JWT token from server
├── Update local JWT and continue operations
└── Save new expiry time to flash memory

Refresh Token Rotation¶

When refresh token expires in <24 hours:
├── Send rotation request with current refresh token  
├── Receive BOTH new JWT + new refresh token
├── Update both tokens locally
├── Reset expiry timers for new cycle
└── Save everything to flash memory

📱 Device Registration Flow¶

1. Dashboard Token Generation¶

User creates device in JunctionRelay dashboard
├── Server generates secure registration token
├── Token contains device name and server public key
└── Token expires in 15 minutes

2. ESP32 Registration¶

Device receives registration token via serial/code
├── Extracts server public key for encryption
├── Sends registration request with device MAC address
├── Server validates token and creates device record
└── Receives initial JWT + refresh token pair

3. Persistent Storage¶

All tokens and keys stored in ESP32 flash memory:
├── Device JWT token + expiry timestamp
├── Refresh token + expiry timestamp  
├── Server public key for encryption
└── Device registration status

🛡️ Security Features¶

End-to-End Encryption¶

All sensor data encrypted using ECDH + AES-GCM
Ephemeral key exchange prevents replay attacks
Server public key verified during registration

Token Security¶

JWT tokens use strong HMAC-SHA256 signatures
Refresh tokens are cryptographically random
Automatic rotation prevents long-term token exposure

Failure Recovery¶

Invalid tokens trigger automatic re-registration
Network failures don't interrupt token timers
Flash storage survives device reboots/power loss

🔧 Test Mode vs Production¶

Test Mode (`#define TESTING_MODE`)¶

Perfect for development and debugging:

JWT Lifetime:     6 minutes   (vs 8 hours production)
Refresh Lifetime: 18 minutes  (vs 7 days production)  
Refresh Interval: 5 minutes   (vs 1 hour production)
Rotation Trigger: 1 minute    (vs 24 hours production)

Production Mode¶

Optimized for real deployments:

JWT Lifetime:     8 hours     (minimal refresh overhead)
Refresh Lifetime: 7 days      (weekly token rotation)
Refresh Interval: 1 hour      (proactive refresh)
Rotation Trigger: 24 hours    (plenty of time for retry)

📊 Operation Timeline¶

Typical Production Day (Test Mode: 20 minutes)¶

00:00 - Device Registration
      ├── Initial JWT + refresh token received
      └── Begin health reporting

01:00 - JWT Refresh #1
      ├── Request new JWT using refresh token
      └── Continue operations seamlessly

02:00 - JWT Refresh #2
      ├── Another automatic JWT renewal
      └── No interruption to device functionality

...

6 days later - Refresh Token Rotation
      ├── Refresh token near expiry (24hr warning)
      ├── Request new JWT + refresh token pair
      ├── Reset 7-day rotation cycle
      └── Continue uninterrupted operation

🚀 Key Benefits¶

Zero Maintenance: Devices stay connected indefinitely without manual intervention
Robust Security: Regular token rotation limits exposure from compromised tokens
Seamless Operation: Token management happens transparently in background
Network Resilient: Failed refreshes automatically retry with fallback strategies
Development Friendly: Test mode provides rapid iteration cycles for debugging

This token management system ensures your ESP32 devices maintain secure, reliable connectivity to JunctionRelay Cloud for months or years without requiring any manual token updates or device re-registration.