Console

La console (/api/v1/console/*) est la surface libre-service derrière le portail bloonio_chat_admin_ssr (port 4318). Un admin s’inscrit (par OTP e-mail), possède un espace de travail (workspace), et y gère ses tenants, opérateurs, membres et invitations — sans jamais toucher à la clé admin de plateforme.

L’authentification est un jeton de console (console_token, HS256, ~7 jours, kind=tenant_admin), scopé à travers les appartenances aux espaces de travail.

Console vs X-Admin-Key

La Gestion des tenants décrit la surface X-Admin-Key (opérateur de plateforme). La console expose des opérations équivalentes (provisionner un tenant, faire tourner les clés, etc.) mais scopées à l’espace de travail de l’admin connecté, via le jeton de console.

Inscription (publique, par OTP)

L’inscription est en deux étapes et atterrit toujours dans un espace de travail — créé depuis organization_name, ou rejoint via un invite_token.

1. Démarrer — POST /console/register crée un compte PENDING et envoie un OTP par e-mail. En dev local (ENV=local, SMTP non configuré), la réponse renvoie l’OTP dans dev_otp.
2. Vérifier — POST /console/verify/registration valide l’OTP, active le compte, crée (ou rejoint) l’espace de travail et renvoie une session.
3. Renvoyer (au besoin) — POST /console/resend/registration-otp.

curl $BASE_URL/api/v1/console/register \
  -X POST -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme.com",
    "password": "une-phrase-de-passe-forte",
    "display_name": "Alex Admin",
    "organization_name": "Acme Co"
  }'

Connexion et MFA

POST /console/login authentifie par e-mail + mot de passe. Le résultat est discriminé par redirect_to_mfa :

• false — pas de second facteur : la session complète (avec console_token) est renvoyée.
• true — un challenge_token et la liste mfa_factors (par exemple ["email", "totp"]) sont renvoyés ; il faut compléter un second facteur.

OTP e-mail

# 1. Login → renvoie un challenge_token quand redirect_to_mfa = true
curl $BASE_URL/api/v1/console/login -X POST -H "Content-Type: application/json" \
  -d '{"email":"admin@acme.com","password":"..."}'

# 2. Émettre l'OTP du second facteur
curl $BASE_URL/api/v1/console/get/login-otp -X POST -H "Content-Type: application/json" \
  -d '{"challenge_token":"chl_..."}'

# 3. Vérifier l'OTP → session complète
curl $BASE_URL/api/v1/console/verify/login-otp -X POST -H "Content-Type: application/json" \
  -d '{"challenge_token":"chl_...","code":"123456"}'

TOTP (Bloonio Authenticator)

L’OTP e-mail est le facteur local toujours disponible. Le facteur TOTP (application Bloonio Authenticator) est délégué à bloonio_auth_relay — chat_relay y est lui-même un tenant. La vérification se fait via POST /console/verify/login-totp avec le challenge_token et le code totp.

Les routes protégées de la console exigent ensuite l’en-tête Authorization: Bearer <console_token>.

Console système

La console système (/api/v1/console/system/*) est la surface super-admin de toute la plateforme. Un compte est super-admin lorsque son champ is_system vaut vrai — c’est le seul booléen qui distingue un compte.

Sémantique 404, pas 403

Les routes /system/* répondent 404 (et non 403) à un compte non-système : la surface n’est pas annoncée. Un appelant sans is_system ne peut donc même pas déduire de l’existence de ces routes.

Elle expose, entre autres, des compteurs de plateforme et des lectures globales :

Méthode	Chemin	Rôle
GET	/system/fetch/stats	Compteurs (espaces, admins, tenants, opérateurs, affectations en attente)
GET	/system/fetch/workspaces	Tous les espaces de travail
GET	/system/fetch/tenants	Tous les tenants (?status=active|suspended)
GET	/system/fetch/admins	Tous les comptes (hachages exclus)
POST	/system/suspend/tenant	Suspension à l’échelle plateforme
POST	/system/reactivate/tenant	Réactivation

Amorcer un super-admin

Trois façons de créer un compte is_system, de la plus forte à la plus faible :

1. Seed déterministe (recommandé). Définissez SYSTEM_ADMIN_EMAIL + SYSTEM_ADMIN_PASSWORD (et l’optionnel SYSTEM_ADMIN_DISPLAY_NAME). Au démarrage, le relais s’assure qu’un super-admin connectable existe. Idempotent : un compte déjà présent est promu sur place et son mot de passe n’est jamais réinitialisé. Pour l’exécuter à la demande, sans redéploiement :

   ENV=production python3 bash/seeds/bootstrap-system-admin.py \
     --email ops@bloonio.com --password '<mot-de-passe-fort>'

   Sans --email/--password, le script retombe sur SYSTEM_ADMIN_EMAIL / SYSTEM_ADMIN_PASSWORD du .env sélectionné par ENV.

2. Liste d’autorisation. Les e-mails de la csv SYSTEM_ADMIN_EMAILS deviennent is_system dès qu’ils s’inscrivent ou se connectent (ils choisissent leur propre mot de passe).

3. Trappe de secours runtime. Promouvoir un compte existant via la clé admin :

   curl "$BASE_URL/api/v1/console/promote/console-admin?email=ops@bloonio.com" \
     -X POST -H "X-Admin-Key: YOUR_ADMIN_KEY"

Trois mécanismes distincts

Le seed crée/répare un compte précis (idempotent). La liste d’autorisation ne promeut que les comptes qui s’inscrivent eux-mêmes. La trappe /promote est l’échappatoire opérateur quand la csv ne peut pas être éditée et redéployée tout de suite.

Étapes suivantes

• La surface publique exacte de la console. Voir la Référence API.
• Gérer les tenants côté plateforme. Voir Gestion des tenants.
• Provisionner des opérateurs. Voir Opérateurs.