When a new StateWarden Agent boots up for the first time, it has zero access to your Realm. It cannot communicate with the Control Plane (Artemis), and it cannot access your Data Plane (Driad). It is fully isolated until explicitly authorized.
This process of authorization is called Pairing.
The Flaw with Standard API Keys
Traditional software often uses static, pre-shared "API Keys" for agent authentication. This is an unacceptable security risk in the HighSec philosophy. If an API key is extracted from a compromised machine's filesystem or memory, the attacker gains permanent, unchecked access to the control API.
StateWarden completely eliminates shared secrets. We use a Challenge-Response Mutual TLS (mTLS) architecture.
The Pairing Process
When you pair a device, you are not simply "logging in". You are establishing a permanent, mathematically proven identity for that specific physical machine.
- Generate a Pairing Code: In the Dashboard, navigate to your Realm's Devices view and click Add Device. This generates a temporary, single-use, cryptographically secure OTP (One Time Password).
- Execute the Init Command: On the target machine where the agent is installed, run the initial pairing command via our CLI (e.g.,
sw init <YOUR-CODE>). - The mTLS Handshake (Under the Hood):
- The Agent generates a private/public key pair locally in memory. The private key never leaves the agent's memory.
- The Agent submits the public key along with the OTP to the Control Plane.
- The Control Plane cryptographically validates the OTP. If valid, it signs the public key and issues a unique Client Certificate bound exclusively to that device.
- The OTP is instantly burned.
The Result: True Zero-Trust Communication
From that moment on, the Agent communicates with StateWarden using its unique Client Certificate (mTLS). There are no passwords to steal, no API keys to leak, and no session tokens to hijack.
Every single API request between the Agent and the Control Plane is mutually authenticated and encrypted at the transport layer, even before the payload itself is evaluated. If an attacker tries to intercept or modify a request, the cryptographic signature fails, and the connection is immediately dropped by Artemis.