For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /fr/docs/web/api.md (or send Accept: text/markdown).

API publique, clés et webhooks

La surface REST versionnée sur laquelle vos clients construisent.

Poser une question sur ce guide

Avant de commencer

Ouvrez votre projet supastack téléchargé dans Visual Studio Code en utilisant Fichier → Ouvrir le dossier, puis choisissez Terminal → Nouveau terminal. La racine du référentiel est le dossier contenant package.json, les applications et les packages. Exécutez la commande ci-dessous et laissez son terminal ouvert. Si une commande n'est pas reconnue, terminez le guide d'installation de l'outil avant de continuer.

Lisez d’abord le didacticiel de la plateforme. Un serveur est le processus d'application qui répond aux requêtes du navigateur ou du téléphone. Le Web lit apps/web/.env.local, Expo lit apps/mobile/.env.local et les commandes de migration de base de données lisent root .env. La démonstration sans base de données/tableau de bord est distincte des comptes réels/auth, qui nécessitent une migration Postgres. Un paiement sur téléphone ou sur ordinateur uniquement nécessite un backend Web exécuté séparément.

corepack pnpm --filter @supastack/web dev

Configuration et paramètres

packages/api définit le contrat versionné : des schémas zod pour chaque requête et réponse, l'enveloppe d'erreur, et le document OpenAPI servi à /api/v1/openapi et rendu à /api/docs. Les clés API de workspace se créent sous Paramètres → Développeurs ; le texte en clair s'affiche une fois, puis seule la clé hachée persiste.

Les clés sont préfixées (sk_<env>_…), scopées (lecture par défaut) et résolues vers un workspace à chaque requête. Les abonnements webhook sortants se gèrent depuis la même surface Développeurs.

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

Processus d’implémentation

Authentifiez-vous avec la clé Bearer ; le serveur résout le workspace depuis la clé, jamais depuis un id fourni par le client. Gardez les formes de réponse versionnées — changements additifs dans v1, changements cassants derrière une nouvelle version.

Pour les webhooks sortants, abonnez une URL d'endpoint au catalogue d'événements ; les livraisons sont signées et enregistrées pour que les consommateurs puissent vérifier et rejouer. Utilisez webhook-events.ts pour le catalogue et webhook-delivery.ts pour les tentatives.

Vérification et dépannage

Vérifiez qu'une clé révoquée renvoie 401, qu'une clé sous-scopée est refusée et que le document OpenAPI se parse. Pour les webhooks, testez la vérification de signature, la relivraison après échec et que les payloads d'événements ne portent jamais de secrets fournisseur.