> ## Documentation Index
> Fetch the complete documentation index at: https://supastack.dev/llms.txt
> Use this file to discover all available pages before exploring further.
> For the full documentation corpus in one file, fetch: https://supastack.dev/llms-full.txt

# API publique, clés et webhooks

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

## 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.

[Installez les outils et récupérez le code](https://supastack.dev/fr/docs/web/before-you-start.md)

[Apprendre les commandes, les fichiers et la configuration](https://supastack.dev/fr/docs/web/terminal-basics.md)

[Terminez le didacticiel Web de première exécution](https://supastack.dev/fr/docs/web/ship-in-5-minutes.md)

```
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.


## Suivant

[Stockage de fichiers](https://supastack.dev/fr/docs/web/storage.md)