Documentation
Welcome to the AuthGrid documentation. Here you’ll find guides for getting started, technical specifications, and advanced configuration options.
Getting Started
New to KeyForge? Start here:
- Hardware Requirements - What you need to build a KeyForge
- Building the Firmware - Compile from source
- Flashing Your Device - Initial setup and OTA updates
- First Use - Registering your first credential
Hardware
KeyForge is built on the Seeed XIAO ESP32-S3. This board provides:
| Feature | Specification |
|---|---|
| MCU | ESP32-S3 (dual-core Xtensa LX7, 240 MHz) |
| USB | Native USB OTG |
| Flash | 8MB |
| Touch | Capacitive touch capable GPIO |
| Form Factor | 21 x 17.5mm |
Purchase the board from Seeed Studio or other electronics retailers.
Building the Firmware
Prerequisites
- PlatformIO (CLI or VSCode extension)
- Git
Clone and Build
git clone https://github.com/authgrid-io/keyforge
cd keyforge
# Development build
pio run -e seeed_xiao_esp32s3
# Secure build (recommended for production)
pio run -e seeed_xiao_esp32s3_secure
Flashing Your Device
Initial Setup (New Device)
cd tools/keyforge-flash
./keyforge-flash --setup
This flashes the bootloader, partition table, and firmware. On first boot, the device will:
- Generate a random master seed
- Burn security eFuses (Secure Boot, NVS encryption key)
- Initialize the credential store
OTA Updates (Existing Device)
cd tools/keyforge-flash
./keyforge-flash
No disassembly required. Updates are verified and can roll back automatically if they fail.
First Use
- Plug in your KeyForge device
- Navigate to a WebAuthn-enabled site (e.g., webauthn.io)
- Click Register
- When prompted, set a PIN (4+ characters)
- Touch the capacitive pad on the device to approve
- Your credential is now stored on the device
Advanced Topics
- Backup and Restore - Export your master seed for recovery
- NVS Encryption - Hardware-backed data-at-rest encryption
- Secure Boot - Firmware signature verification
- SSH Authentication - Using KeyForge for SSH keys
API Reference
KeyForge implements the CTAP2 specification with the following commands:
| Command | Description |
|---|---|
authenticatorGetInfo | Device capabilities and configuration |
authenticatorMakeCredential | Create a new credential |
authenticatorGetAssertion | Authenticate with an existing credential |
authenticatorGetNextAssertion | Iterate multiple credentials |
authenticatorClientPIN | PIN management |
authenticatorCredentialManagement | List and delete credentials |
authenticatorReset | Factory reset |
Need Help?
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Community Q&A
- Email - support@authgrid.io