FAQ¶
Why RS256 instead of HS256?¶
RS256 (asymmetric) allows other services to verify tokens using the public key without knowing the signing secret. The JWKS endpoint exposes the public key for service-to-service validation.
What about post-quantum algorithms?¶
Pico-Auth supports ML-DSA-65 (NIST Level 3) and ML-DSA-87 (NIST Level 5) as alternatives to RS256. Set AUTH_ALGORITHM=ML-DSA-65 and install the pqc extra (pip install pico-auth[pqc]). ML-DSA uses liboqs-python for signing and verification.
Where are the keys stored?¶
By default in ~/.pico-auth/. The directory is created automatically on first run. The private/secret key file has 0600 permissions. Configure with AUTH_DATA_DIR.
- RSA:
private.pem+public.pem - ML-DSA:
pqc_secret.bin+pqc_public.bin
Can I use PostgreSQL instead of SQLite?¶
Yes. Set the DATABASE_URL environment variable:
Why do errors return HTTP 200?¶
Pico-Auth returns errors in the JSON body ({"error": "message"}) rather than using HTTP status codes. This simplifies client-side handling and is consistent across all endpoints.
How does refresh token rotation work?¶
Each refresh token can only be used once. When you call /refresh, the old token is deleted and a new one is issued. If someone steals a token and uses it first, your next refresh will fail -- this signals a potential compromise.
How do I create the first admin user?¶
By default, auto_create_admin: true creates an admin user on startup. Set AUTH_ADMIN_EMAIL and AUTH_ADMIN_PASSWORD environment variables for production.
What roles are available?¶
Four built-in roles: superadmin, org_admin, operator, viewer. Only superadmin and org_admin can access admin endpoints (list users, update roles).