API institutionnelle pour fédérations

Avant de commencer — conduite du changement

L'intégration technique prend dix minutes. Mais avant d'écrire la moindre ligne de code, il faut parler de la couche humaine — celle qui détermine si vos clubs affiliés utilisent réellement l'outil, ou s'ils créent un dossier « Paak » dans leur boîte mail qu'ils n'ouvrent jamais.

Une fédération qui mandate Paak à ses clubs obtient typiquement :

• Une vague initiale de résistance — les présidents de clubs sont des bénévoles, déjà submergés, qui voient toute nouvelle obligation comme « une chose de plus à faire ».
• Des inscriptions de surface — le club crée un compte parce qu'on lui demande, mais n'importe pas ses adhérents, ne configure pas ses cotisations, et n'active pas le partage territorial. Votre tableau de bord reste vide.
• Un désabonnement de masse à 12 mois — un club qui souscrit sous pression résilie à la première occasion. Un club qui souscrit volontairement devient un ambassadeur interne.

Le rythme qui fonctionne :

1. Identifiez un président de club que vous connaissez personnellement et qui est curieux des outils numériques. C'est votre club pilote. Pas trois clubs, un seul.
2. Présentez Paak en partant de ce qui change pour lui : moins de tableurs, des relances automatiques pour les cotisations, des inscriptions qui se remplissent toutes seules. La remontée territoriale est un effet de bord, pas l'argumentaire.
3. Proposez un accompagnement à la configuration — une heure en visio avec le président pour l'aider à importer ses adhérents et activer le partage. L'onboarding Paak prend trente secondes pour quelqu'un qui sait, beaucoup plus pour un bénévole qui n'a jamais utilisé de SaaS.
4. Laissez la nouvelle se propager par bouche-à-oreille. Votre tableau de bord territorial se met à jour dès qu'un seul club active le partage — vous n'avez pas besoin d'une couverture à 100 % pour commencer à exploiter les données.
5. Quand vous communiquez à l'ensemble de votre territoire, écrivez « nous recommandons », pas « nous imposons ». Mentionnez un ou deux clubs pilotes pour la preuve sociale. Donnez l'e-mail contact@paak.club pour que les clubs hésitants puissent poser leurs questions directement à l'équipe Paak, sans passer par vous.

Un playbook complet (mail-type, points de discussion pour votre AG, cadence pilote) est en cours de rédaction. Demandez la version en avance sur contact@paak.club.

À quoi sert cette API

Trois cas d'usage principaux :

• Tableau de bord interne — vous avez déjà un tableau de bord fédéral construit en interne (Power BI, Looker, Metabase, ou autre). L'API Paak vous permet d'alimenter ce tableau de bord avec les agrégats territoriaux en temps réel, sans vous reposer sur l'interface Paak.
• Outil comptable / CRM — exporter automatiquement, chaque nuit, les effectifs par club pour les croiser avec vos propres données (licences vendues, cotisations fédérales perçues).
• Dossier de subvention — récupérer le dossier CERFA/FDVA en format CSV pour l'injecter dans votre processus de demande de subvention auprès de l'ANS, de la DRAJES, ou du conseil départemental.

Ce que vous pouvez récupérer (et ce que vous ne récupérerez pas)

L'API renvoie uniquement des compteurs agrégés. Aucun nom, aucune date de naissance, aucune adresse e-mail individuelle ne transite par l'API institutionnelle. Cette posture est intentionnelle et tient à deux contraintes :

• Base juridique RGPD : les institutions territoriales (CDOS, CROS) n'émettent pas les licences sportives et n'ont donc pas de motif d'intérêt légitime à recevoir les données nominatives individuelles. Les agrégats statistiques restent dans le périmètre acceptable de l'article 6.1.f.
• Consentement du club : chaque club admin peut désactiver le partage à tout moment, institution par institution. Tant que le club n'a pas activé le partage, votre clé d'accès ne voit rien de ce club — même si le club est dans votre territoire ou affilié à votre fédération.

Vous pouvez récupérer :

• Effectifs licenciés totaux du territoire, ventilés par sport, par tranche d'âge, par genre.
• Nombre d'encadrants par club avec statut honorabilité (valides, expirent dans 30 jours, expirés, jamais vérifiés).
• Pourcentage de conformité par club, classement RAG (vert ≥ 80 %, ambre 50-79 %, rouge < 50 %).
• Pour les CROS : pivot par département de la région.
• Liste des clubs partageant leurs données, avec ville et code postal.
• Dossier CERFA/FDVA complet, en CSV semicolon-delimited, ouvrable directement dans Excel-FR.

Vous ne pouvez PAS récupérer :

• Les noms, prénoms, e-mails, numéros de téléphone, dates de naissance des licenciés ou encadrants.
• Les attestations d'honorabilité elles-mêmes (numéros, dates de délivrance).
• Les certificats médicaux, dossiers d'inscription, données médicales.
• Les données de paiement ou d'historique financier des clubs.
• Les données de clubs qui n'ont pas activé le partage avec votre institution.
• Les données des « clubs fantômes » (clubs non-Paak que vous avez saisis manuellement depuis votre tableau de bord) — par construction, ces enregistrements ne contiennent que des effectifs agrégés que vous avez vous-mêmes saisis, jamais de données nominatives.

Pour les fédérations qui souhaitent récupérer les données licence par licence (les licences qu'elles émettent déjà, donc qu'elles détiennent déjà en interne), un cas d'usage spécifique est possible — voir la section « Et les données licence par licence ? » plus bas.

Obtenir une clé d'accès

Les clés d'accès institutionnelles sont émises uniquement par l'équipe Paak pour le moment (Phase 3 du déploiement institutionnel — l'auto-émission depuis votre propre interface viendra dans une phase ultérieure).

Pour demander une clé, écrivez à contact@paak.club avec :

• Le nom officiel de votre institution (fédération, CDOS, CROS).
• Le nom et la fonction du contact technique qui utilisera la clé (typiquement votre DSI, votre prestataire IT, ou un développeur interne).
• Un libellé court qui décrit l'usage (ex. : « Intégration Power BI prod », « Synchronisation nocturne CRM »). Ce libellé apparaîtra dans la liste de vos clés actives pour identification.
• Une adresse e-mail dédiée à recevoir la clé en plaintext.

L'équipe Paak génère la clé et vous la transmet par e-mail chiffré. La clé est affichée une seule fois — au moment de la création — et n'est jamais redonnée ensuite. Stockez-la immédiatement dans votre gestionnaire de secrets (Vault, 1Password, AWS Secrets Manager, Azure Key Vault, etc.).

Une clé a la forme suivante : pat_8f3c1a2b... (43 caractères après le préfixe). Le préfixe pat_ permet de reconnaître facilement une clé Paak dans vos journaux et secrets manager.

Authentification

Présentez la clé dans l'en-tête HTTP Authorization sur chaque requête :

Authorization: Bearer pat_8f3c1a2b...

Le serveur identifie votre institution à partir de la clé. Aucun autre paramètre n'est requis pour identifier votre territoire — la clé est l'unique source de vérité.

Si la clé est invalide, révoquée, ou expirée, vous recevez une réponse 401 Unauthorized avec un corps JSON :

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or revoked API key"
  }
}

Sécurité — ce qui est en place côté Paak

Votre clé d'accès est une credential sensible — au même titre qu'un mot de passe administrateur. Voici, en clair, les protections que nous avons mises en place pour qu'elle reste utile sans devenir un point d'attaque.

Génération et stockage de la clé

• Entropie 256 bits — chaque clé est générée à partir de 32 octets aléatoires cryptographiques (crypto.randomBytes), encodés en base64url. Une clé Paak ne peut pas être devinée par force brute dans un temps raisonnable, même par un acteur étatique.
• Hachage SHA-256 au repos — la base de données Paak ne stocke pas votre clé en clair. Elle stocke uniquement le hash SHA-256. Si la base de données venait à fuiter, votre clé reste secrète : le hash ne peut pas être inversé pour retrouver le plaintext.
• Plaintext jamais redonné — la clé en clair vous est transmise une seule fois, au moment de la création. Si vous la perdez, elle est définitivement perdue : vous devez en demander une nouvelle. Cette contrainte est volontaire — elle élimine la possibilité d'une fuite par un employé Paak qui consulterait les clés en bases.

Transit et hébergement

• TLS 1.3 obligatoire — toutes les communications avec api.paak.club sont chiffrées de bout en bout. Les versions TLS antérieures sont refusées au niveau du serveur Nginx. Certificats Let's Encrypt renouvelés automatiquement.
• Hébergement EU souverain — OVHcloud, datacenter Roubaix (France). Aucun trafic ne sort du territoire européen pour le fonctionnement de l'API. Pas de CDN US, pas de proxy intermédiaire.
• Pas d'écriture, jamais — l'API institutionnelle est strictement en lecture seule. Une clé compromise ne peut pas modifier de données, ni supprimer de comptes, ni envoyer d'e-mails depuis Paak. La surface d'attaque est limitée à la lecture de données déjà agrégées.

Contrôles à chaque requête

• Triple vérification de la clé à chaque appel : (1) le hash correspond bien à une clé enregistrée, (2) la clé n'a pas été révoquée, (3) l'organisation associée est bien de type FÉDÉRATION / CDOS / CROS (et non un club ou un type inconnu — cette vérification est une ceinture-et-bretelles en cas de dérive future de la configuration).
• Périmètre dérivé de la clé, pas du body : l'identifiant de votre institution est lu depuis le hash de la clé côté serveur — jamais depuis un paramètre d'URL ou un champ du body. Une requête malicieuse qui tenterait d'injecter « organizationId: autre_federation » dans le body est silencieusement ignorée. Vous ne voyez que votre territoire, jamais celui d'une autre institution.
• K-anonymité côté SQL : la règle « regrouper les clubs < 5 encadrants dans une ligne anonyme » est appliquée dans la requête de la base de données — pas dans le template d'affichage. Impossible de la contourner via un paramètre d'API.
• Filtre de consentement obligatoire : chaque requête ré-évalue, au moment de l'appel, quels clubs ont activé le partage avec votre institution. Un club qui a désactivé le partage depuis hier n'apparaît plus dans la réponse d'aujourd'hui, même si votre clé était valide hier. Aucun cache, aucune fenêtre de grâce.

Limite de débit (rate limit)

• 60 requêtes par heure par clé, par défaut. Une clé compromise ne peut donc, au pire, extraire les agrégats que 60 fois par heure avant de déclencher des 429 Too Many Requests. Ces 429 sont un signal clair pour nos ops, et déclenchent une investigation côté Paak ainsi qu'un contact préventif vers l'institution propriétaire de la clé.
• Bucketing par clé, pas par IP — si vous avez plusieurs serveurs derrière un NAT, ils partagent le quota de la clé. Si vous avez plusieurs clés (dev, staging, prod), chacune a son propre quota.

Journalisation forensique

• Chaque appel authentifié est enregistré dans une table dédiée institutional_api_key_usage : IP source, user-agent, endpoint appelé, code de réponse, horodatage à la milliseconde. Cette table n'est consultable que par les ops Paak.
• Usage prévu : investigation après suspicion de compromission, audit annuel des schémas d'usage, détection d'anomalies (pic d'appels inhabituel, appels depuis un pays qui n'est pas le vôtre, etc.).
• Conservation : politique de rétention en cours de calibrage avec notre conseil juridique. Vous pouvez demander à tout moment l'extraction des journaux liés à votre clé en écrivant à contact@paak.club — c'est votre droit en tant que responsable de traitement institutionnel.

Révocation

• Soft-delete avec traçabilité : une clé révoquée n'est pas supprimée de la base. Son enregistrement est marqué d'un horodatage revokedAt. La vérification à chaque appel refuse les clés ayant ce champ non-nul. La piste d'audit reste intacte : si une clé révoquée avait été utilisée avant révocation, ses appels historiques restent traçables dans institutional_api_key_usage.
• Délai de révocation : instantané — l'effet est visible dès le prochain appel. Pas de cache, pas de propagation à attendre.

Données qui restent inaccessibles, par construction

Au-delà du filtre d'agrégation, certaines données ne sont physiquement pas accessibles via l'API institutionnelle, même par accident :

• Données nominatives (noms, e-mails, dates de naissance) — les endpoints ne lisent jamais la table des contacts. Le code SQL est explicitement écrit pour ne sélectionner que des compteurs et statuts, jamais des champs de type « nom ».
• Données financières (cotisations payées, historique Mollie) — aucun endpoint institutionnel ne touche aux tables de paiement.
• Données médicales (certificats médicaux, notes de blessure) — aucun endpoint institutionnel ne touche aux tables de qualifications médicales.
• Données des clubs fantômes (clubs non-Paak saisis manuellement par d'autres institutions) — votre clé ne voit que les clubs qui ont explicitement activé le partage avec vous. Les clubs fantômes d'autres institutions vous sont invisibles, et les vôtres ne contiennent que les effectifs agrégés que vous avez vous-même saisis.

Posture générale

Cette API est conçue selon le principe du privilège minimal — vous ne recevez que ce qui est strictement nécessaire à votre mission territoriale ou fédérale, et rien d'autre. Si vous avez un cas d'usage qui nécessite plus de données, ce ne sera pas une élévation de privilèges sur la même clé : ce sera un nouveau type d'endpoint, un nouvel accord contractuel, et une nouvelle catégorie de clé — pour que la surface d'attaque reste compartimentée.

Endpoints disponibles

Base URL : https://api.paak.club/api/v1/institutional

Tous les endpoints sont en GET (lecture seule) :

GET /scope

Diagnostic. Renvoie l'identité de votre institution + la liste des clubs qui partagent actuellement avec vous (juste les identifiants — pas les données). Utile comme test de connexion avant les autres appels.

GET /honorabilite-summary

Synthèse honorabilité. Renvoie :

• totals — totaux territoriaux (nombre d'encadrants, vérifiés, expirant bientôt, expirés, jamais vérifiés, % de conformité).
• perClub — un tableau de lignes par club, chacune avec ses propres compteurs + classement RAG. Les clubs de moins de 5 encadrants sont regroupés dans une ligne anonyme (« k-anonymité ») pour empêcher la ré-identification individuelle par triangulation.

GET /licenses-summary

Effectifs licenciés. Renvoie :

• totals — total licenciés, ventilation F/M/non-renseigné, part féminine en %.
• bySport — pivot par sport (uniquement les sports ≥ 5 licenciés sur votre territoire).
• byAgeBracket — pyramide des âges en 6 tranches (U-13, 13-17, 18-25, 26-39, 40-64, 65+).
• perClub — pivot par club avec k-anonymité.

GET /regional-drilldown

Pivot par département (utile pour les CROS qui veulent identifier quel département concentre les effectifs ou décroche sur la conformité). K-anonymité ≥ 5 enforcée au niveau du département.

GET /dossier-export?year=YYYY&asOfDate=YYYY-MM-DD

Dossier CERFA/FDVA. Renvoie un fichier CSV semicolon-delimited avec BOM UTF-8 (ouvre directement dans Excel-FR). Quatre sections : totaux, par sport, pyramide des âges, par département.

• year — année de référence affichée en en-tête (défaut : année courante).
• asOfDate — date d'observation. Par défaut, le rapport reflète la situation d'aujourd'hui. Pour un bilan d'année fiscale, passez YYYY-12-31 de l'année concernée. Format strict YYYY-MM-DD ; tout autre format renvoie 400.

GET /children

Liste des clubs partageant actuellement avec vous, avec leur nom, code postal, ville, et date de création. Aucune donnée d'adhérent.

Exemple complet — script de synchronisation nocturne

Voici un script minimal en curl + jq qui récupère la synthèse honorabilité et l'écrit dans un fichier JSON. Adaptez le format pour votre stack :

#!/bin/bash
set -euo pipefail

PAAK_API_KEY="${PAAK_API_KEY}"  # depuis votre secrets manager
BASE="https://api.paak.club/api/v1/institutional"

# 1. Test de connexion
curl -s -H "Authorization: Bearer $PAAK_API_KEY" "$BASE/scope" | jq .

# 2. Récupérer la synthèse honorabilité du jour
curl -s -H "Authorization: Bearer $PAAK_API_KEY" \
  "$BASE/honorabilite-summary" \
  | jq . > "/var/data/paak/honorabilite-$(date +%Y-%m-%d).json"

# 3. Dossier CERFA pour l'année fiscale précédente
LAST_YEAR=$(($(date +%Y) - 1))
curl -s -H "Authorization: Bearer $PAAK_API_KEY" \
  "$BASE/dossier-export?year=$LAST_YEAR&asOfDate=$LAST_YEAR-12-31" \
  -o "/var/data/paak/dossier-$LAST_YEAR.csv"

echo "Synchronisation Paak terminée."

Limites techniques (rate limit, journalisation)

• Rate limit : 60 requêtes par heure par clé. Bien suffisant pour une synchronisation nocturne ou même horaire. Si vous dépassez, vous recevez 429 Too Many Requests avec un en-tête Retry-After. Si vous avez un cas d'usage qui justifie une limite plus haute (synchronisation temps réel par exemple), contactez-nous.
• Journalisation : chaque appel authentifié est journalisé côté Paak (IP source, user-agent, endpoint, code de statut). Cette traçabilité est utilisée uniquement pour la résolution d'incidents de sécurité ou pour répondre à une demande de vos services de sécurité. Les journaux ne sont pas exposés publiquement.
• Disponibilité : l'API suit la disponibilité globale de la plateforme Paak. Statut en temps réel sur status.paak.club.

Que se passe-t-il si un club retire son consentement ?

Les agrégats territoriaux que votre clé renvoie reflètent en temps réel le périmètre des clubs ayant activé le partage. Si un club désactive le partage depuis ses paramètres, son contribution disparaît de la prochaine réponse de l'API — totaux et lignes per-club incluses.

Conséquence : les chiffres peuvent évoluer d'une exécution à l'autre, même sur la même journée. Si vous calculez des indicateurs de tendance ou rendez des rapports historiques, snapshotez les réponses côté votre système (et conservez-les avec leur date) plutôt que de re-requêter l'historique à chaque besoin.

Révoquer une clé compromise

Si vous suspectez une fuite (clé apparue dans un dépôt public, ordinateur volé, départ d'un prestataire), écrivez immédiatement à contact@paak.club avec le préfixe de la clé (pat_xxxxxxxx — les 8 premiers caractères suffisent). L'équipe Paak la révoque dans la minute ; la prochaine requête utilisant la clé renvoie 401.

En parallèle, une nouvelle clé vous est émise. La révocation est définitive — une clé révoquée ne peut pas être réactivée.

Et les données licence par licence ?

Spécifique aux fédérations sportives délégataires (FFF, FFR, FFHG, FFSG, etc.) qui émettent elles-mêmes les licences :

Sur le plan juridique, votre fédération est déjà responsable de traitement des licences qu'elle émet — vous détenez les noms, dates de naissance, clubs d'affiliation des licenciés dans votre propre SI fédéral. Paak peut, en théorie, vous restituer ces données licence par licence pour les clubs ayant souscrit à Paak (clubs qui consentent par construction à ce que leurs adhérents soient visibles par la fédération qui les licencie).

Cette fonctionnalité n'est pas encore disponible dans l'API publique. Elle nécessite :

• Un accord de co-responsabilité de traitement au sens de l'article 26 du RGPD, signé entre votre fédération et Emmara (l'éditeur de Paak), précisant la finalité du transfert et les garanties techniques + organisationnelles.
• Une vérification par notre conseil juridique de la délégation ministérielle dont vous bénéficiez (Code du sport L131-8 et suivants) et de votre périmètre de licenciement.
• Une mise à jour de la politique de confidentialité Paak pour informer les adhérents que leurs données pourront transiter vers leur fédération via l'API.

Si vous êtes une fédération délégataire intéressée par ce cas d'usage, écrivez à contact@paak.club avec votre référent juridique en copie. Le déploiement se fait au cas par cas, par fédération, avec contrat dédié.

Contact

Toute question technique, demande de clé, signalement d'incident : contact@paak.club.

Nous répondons sous 24 heures les jours ouvrés (l'équipe est sur le fuseau Europe/Paris). Pour les incidents de sécurité critiques (clé compromise, suspicion d'abus), précisez « [URGENT SÉCURITÉ] » dans l'objet — ces e-mails déclenchent une alerte hors horaires de bureau.