ReCoDanse pour les développeurs

Ce que tu peux construire

Démarrer

1. Ouvre un compte sur https://recodanse.fr et confirme ton adresse e-mail.
2. Déclare ton application. Choisis son espèce : connexion (un site ou une app qui authentifie les ReCoDanseurs·euses) ou service (un logiciel sans humain derrière, qui publie pour toi).
3. Garde le client_secret : il ne se montre qu'une fois.
4. Pose un webhook https:// abonné à autorisation.retiree et à compte.efface, qui vérifie la signature : c'est par lui que tu apprends qu'il faut effacer, et la revue l'éprouve (voir « Essai et revue »).
5. Pour l'ouvrir aux autres, soumets-la à la revue (POST /v0/tiers/applications/{id}/revue) en acceptant la version 2026-10-30 des conditions des développeurs (accepte_les_conditions).

Tu déclares ton application dans l'app, à https://recodanse.fr/developpeur (« Mes applications »), ou en code, avec un jeton de développeur. Le même appel, depuis la console de ton navigateur connecté à https://recodanse.fr :

await fetch('/v0/tiers/applications', {
  method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    nom: 'Billetterie de Nadia', categorie: 'service',
    portees: ['evenements.publier'], site_web: 'https://nadia.example'
  })
}).then(r => r.json())

Pour une application connexion, ajoute redirections (des adresses https://, une boucle locale http://127.0.0.1:…, ou un schéma d'app native) et, pour une app native ou une page web sans serveur, publique: true (pas de secret, PKCE obligatoire).

Les jetons

La porte d'autorisation est https://connexion.recodanse.fr (OAuth 2.0 / OpenID Connect, découverte standard). L'API est https://api.recodanse.fr ; chaque appel porte Authorization: Bearer <jeton>.

Une personne se connecte (code d'autorisation + PKCE)

GET https://connexion.recodanse.fr/oauth2/auth?response_type=code
    &client_id=<client_id>&redirect_uri=<ta redirection>
    &scope=openid%20profile&state=<aléa>
    &code_challenge=<S256(verifier)>&code_challenge_method=S256

POST https://connexion.recodanse.fr/oauth2/token
  grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…

La personne voit une page de ReCoDanse qui nomme ton application et dit, en phrases, ce qu'elle t'accorde ; elle peut décocher. Le sub que tu reçois est un pseudonyme stable et propre à ton application.

Ton logiciel agit pour toi (compte de service)

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d scope=evenements.publier \
  https://connexion.recodanse.fr/oauth2/token

curl -X PUT https://api.recodanse.fr/v1/evenements/soiree-2026-11-07 \
  -H "Authorization: Bearer $JETON" -H 'Content-Type: application/json' \
  -d '{"espece":"social","titre":"Social bachata","danses":["bachata"],
       "debut":"2026-11-07T20:00:00+01:00","fin":"2026-11-08T01:00:00+01:00",
       "lieu":{"nom":"La Halle","ville":"Lyon","latitude":45.7769,"longitude":4.8273},
       "prix_indicatif":"12 €","lien_billetterie":"https://www.helloasso.com/…"}'

La référence (soiree-2026-11-07) est ta clé : republier la même référence corrige l'événement au lieu de le dupliquer.

Publier un agenda

Tu tiens un agenda régional de soirées, et des organisateurs te proposent les leurs ? Ton agenda devient une source parmi d'autres de ReCoDanse : chaque soirée y paraît sous ton nom, à côté de celles des autres agendas. Ce qui compte :

• Une référence stable par soirée — l'UID de ton iCal, l'identifiant de ta base. Republier la même référence corrige ; en changer duplique.
• Ne pousse que ce qui change. Garde une empreinte de ce que tu as envoyé ; une soirée identique n'a pas besoin d'un second PUT. Les 30 prochains jours suffisent : le passé ne se publie pas.
• Une soirée annulée s'annule, elle ne se retire pas : "annule": true garde la fiche et dit « annulée » aux personnes qui comptaient venir. DELETE est pour une fiche qui n'aurait jamais dû exister — et sa référence ne se republie plus.
• Une soirée qui disparaît de ta liste n'est pas forcément annulée : ne l'annonce pas annulée sur une absence.
• Savoir qui propose. Branche « Se connecter avec ReCoDanse » sur ton formulaire de proposition : tu sais qui propose, sans recréer de vérification.

Pas encore là, et dit tel quel : ReCoDanse ne lit pas encore un flux iCal ou JSON que tu déclarerais (pour l'instant, tu pousses) ; une soirée ne peut pas encore nommer la personne qui l'a proposée ; et l'application ne lit pas encore si un compte est vérifié. Tout le reste de cette page marche aujourd'hui.

Les portées

Une application connexion peut demander openid, profile, email, offline_access, videos.lire, videos.ranger, videos.deposer, videos.annoter, programmes.poser, evenements.proposer ; un compte de service : evenements.publier, creneaux.publier. Une portée ne suffit jamais : ReCoDanse vérifie aussi, à chaque appel, que ton application est déclarée, qu'elle n'est pas suspendue, et que la personne ne t'a pas retiré son accord.

Sans webhook d'effacement, des portées limitées. Une app de téléphone ou une page sans serveur n'a pas d'adresse où apprendre qu'un compte s'est effacé : elle ne demande alors que openid et des écritures vers ReCoDanse (ce qui est écrit chez nous s'efface avec le compte). Une portée marquée « exigé » donne quelque chose que tu garderais chez toi : la revue la refuse en 409 portee_sans_webhook_d_effacement tant qu'aucun webhook d'effacement n'est déclaré, et le message nomme les portées à retirer.

Les mots

Nos clés sont en français. Voici ce qu'elles veulent dire en anglais, le terme Schema.org qui y répond, et ce que disent les billetteries et les logiciels de studio que tu connais peut-être.

Pour un programme, ou un LLM, la même table en contexte JSON-LD : appliqué à nos objets, il les fait lire comme des objets Schema.org. Une clé sans équivalent direct n'y est pas.

Essai et revue

Une application naît en développement : seul ton compte peut l'autoriser, et ce qu'elle publie reste un essai que ton compte seul voit (essai: true). Quand elle est prête, soumets-la à la revue (POST /v0/tiers/applications/{id}/revue) : ReCoDanse la publie, et elle s'ouvre à tous les ReCoDanseurs·euses. Une application suspendue s'arrête à la requête suivante.

L'épreuve du webhook d'effacement. Une application connexion qui demande une portée marquée « exigé » ne se soumet, et ne se publie, que si l'un de ses webhooks actifs, abonné à autorisation.retiree et à compte.efface, passe une épreuve jouée à l'instant : un essai signé doit recevoir une réponse 2xx, et le même essai mal signé une réponse 4xx. Sinon, la revue refuse en 409 (portee_sans_webhook_d_effacement s'il n'y en a aucun, webhook_d_effacement_injoignable, webhook_d_effacement_sans_verification) et le message dit le statut reçu ; webhook_d_effacement_retenu dit que le débit des envois a retenu l'essai, et dans combien de secondes réessayer.

Créneaux : publication suspendue. ReCoDanse range, valide et te rend tes créneaux, mais ne les montre à personne d'autre tant qu'un avis juridique (directive européenne DAC7) n'est pas rendu. Chaque réponse le dit : publie: false, raison: publication_suspendue_dac7.

Le bac à sable

Pas encore ouvert. Le bac à sable est prêt dans le code, mais ses adresses ne répondent pas encore. En attendant, une application en développement s'essaie avec ton propre compte (lui seul peut l'autoriser), une adresse de retour en boucle locale (http://127.0.0.1:…), et un tunnel https vers ton poste pour tes webhooks (au bac à sable, http:// suffira).

Quand il ouvrira, pour essayer ton application de bout en bout sans toucher une vraie personne : https://bac-a-sable.recodanse.fr (émetteur https://connexion.bac-a-sable.recodanse.fr). Tu y déclares ton application avec ton compte, puis la page « Autoriser une application » te propose de continuer en tant que l'un des comptes fictifs — leurs vidéos, leurs carnets, leurs cours sont là pour ça. Une application en développement s'y essaie sans revue.

Pour tester tes webhooks, déclenche un événement pour un compte fictif qui a autorisé ton application : POST /v0/tiers/bac-a-sable/evenements {"application", "evenement": "autorisation.retiree" | "compte.efface", "danseuse"}. L'envoi part signé comme en production ; l'accord est retiré, le compte fictif reste.

Tout s'efface à chaque redémarrage du bac à sable, et chaque semaine : ton compte, tes applications et tes webhooks compris. Un jeton du bac à sable ne vaut rien en production ; en production, ton application se déclare à nouveau, et passe la revue. Les quotas et les erreurs sont les mêmes qu'en production.

Webhooks

Donne une adresse https:// (port 443, un hôte public ; au bac à sable, http:// port 80 aussi — un tunnel ngrok, cloudflared ou localtunnel vers ton poste en est un) et choisis tes événements ; ReCoDanse y envoie un POST signé selon Standard Webhooks (en-têtes webhook-id, webhook-timestamp, webhook-signature). Huit tentatives sur environ 37 heures ; un 410 désactive le webhook. Au plus 60 envois par minute vers une même destination (toutes applications confondues) et 120 par minute d'une même application : au-delà, l'envoi est retenu et repart la minute suivante, sans compter de tentative.

• autorisation.retiree — Une personne a retiré l'accès de ton application — `data.sujet` est le `sub` qu'elle avait chez toi
• compte.efface — Un compte qui t'avait autorisé s'est effacé — efface ce que tu gardes de `data.sujet`
• publication.retiree — La modération a retiré un de tes événements — `data.espece`, `data.reference`, `data.id`

import { Webhook } from "standardwebhooks";
const wh = new Webhook(process.env.SECRET_RECODANSE); // whsec_…
const evenement = wh.verify(corpsBrut, entetes);       // lève une erreur si la signature est fausse

La charge ne porte jamais un nom, un e-mail ou un identifiant de compte : une personne y est son sujet, le même sub que dans tes jetons.

Assistants (MCP)

Le serveur MCP est https://api.recodanse.fr/mcp (Streamable HTTP). Un assistant compatible le découvre seul : sans jeton, la réponse 401 nomme https://api.recodanse.fr/.well-known/oauth-protected-resource, qui nomme la porte d'autorisation, qui annonce l'enregistrement (POST /v1/enregistrement, RFC 7591). La personne voit la page de consentement de ReCoDanse — l'assistant y est dit « non vérifié » tant que ReCoDanse ne l'a pas revu.

Outils : chercher_videos, lire_video, mes_carnets, regrouper_videos (lecture) et ranger_video (écriture, portée videos.ranger). Aucun ne rend un film, une vignette ou une adresse de lecture ; aucun ne supprime, ne partage ni ne publie.

Ce que l'API ne fait jamais

• servir un octet vidéo, une vignette, une adresse exacte de domicile, ou une donnée d'un autre compte ;
• laisser sortir l'identifiant interne d'un compte ;
• encaisser ou lire un paiement : un tarif est affiché, le règlement est un lien sortant.

En te servant de l'API, tu t'engages à ne pas reconstituer de données personnelles, à ne pas revendre ce que tu lis, et à effacer ce que tu gardes d'une personne quand elle retire ton application ou efface son compte. Un abus vaut suspension. C'est le résumé des conditions des développeurs, version 2026-10-30.

Référence

Générée du contrat OpenAPI — de quoi générer ton client. Aussi en texte, pour un assistant : llms.txt.

Schémas