Skip to content

Pico-Auth Documentation

Welcome to the official documentation for Pico-Auth, a minimal JWT authentication server for the Pico ecosystem.

What is Pico-Auth?

Pico-Auth is a ready-to-run authentication server built on the pico-framework stack. It provides:

  • JWT tokens with auto-generated key pairs (RS256 default, ML-DSA-65/87 optional)
  • Refresh token rotation with SHA-256 hashed storage
  • Role-based access control (superadmin, org_admin, operator, viewer)
  • Group management with CRUD API, membership, and groups JWT claim
  • OIDC discovery endpoints for service-to-service integration
  • Post-quantum ready: ML-DSA-65 / ML-DSA-87 signing via optional pqc extra
  • Zero-config startup with SQLite and auto-created admin
Document Description
Getting Started Run pico-auth in 2 minutes
Configuration application.yaml settings
API Endpoints Complete REST API reference
Authentication Flow JWT lifecycle and refresh rotation
Architecture Internal design and component wiring
API Reference Python API documentation
Ecosystem Pico framework packages
FAQ Frequently asked questions

Installation

pip install -e ".[dev]"
python -m pico_auth.main

The server starts on http://localhost:8100 with an auto-created admin user.