# Console et API

> La console, l'API publique et Discovery : trois portes d'entrée sur Wakastart, ce que chacune permet et laquelle choisir pour une tâche.

Wakastart s'utilise par trois portes. La **console** sert aux personnes qui administrent. L'**API publique** sert à vos applications et à vos serveurs. **Discovery** sert à la connexion, avant toute authentification. Chaque tâche passe par une porte, parfois par deux.

## Définition

```mermaid
flowchart LR
  ADM([Administrateur]) --> CON["Console<br/>app.wakastart.app"]
  WAK["Votre wakapp<br/>front et back"] --> DIS["Discovery<br/>discovery.wakastart.app"]
  WAK --> API["API publique<br/>api.wakastart.app/api"]
  SRV["Vos serveurs<br/>clé API sk_…"] --> API
  CON --> P["Plateforme Wakastart<br/>organisation · identité · hébergement · modules"]
  API --> P
  DIS --> P
```

| Porte | Adresse | Pour qui | Authentification |
|---|---|---|---|
| **Console** | `https://app.wakastart.app` | administrateurs : partenaires, réseaux, clients | connexion Keycloak, niveau Administrateur client au minimum |
| **API publique** | `https://api.wakastart.app/api` | wakapps et serveurs de vos clients | `Authorization: Bearer <jeton Keycloak>`, `x-enriched-token: <jeton enrichi>` ou `x-api-key: sk_…` ; le jeton doit avoir été émis pour cette application |
| **Discovery** | `https://discovery.wakastart.app` | wakapps, avant la connexion | aucune |

## Pourquoi ça existe

Les besoins diffèrent. Un administrateur veut voir, comparer, confirmer : une interface. Une application veut des réponses rapides, au nom de l'utilisateur connecté et limitées à son organisation : une API. Et la connexion doit commencer avant que l'utilisateur ait le moindre jeton : un service public, Discovery.

## Comment ça marche

### Ce que fait chaque porte

| Tâche | Console | API publique | Discovery |
|---|---|---|---|
| Trouver la page de connexion d'un utilisateur | | | ✔ |
| Lire l'utilisateur connecté, son profil et ses droits | | ✔ `GET /api/me` | |
| Inviter des utilisateurs, gérer équipes et profils d'une organisation | | ✔ | |
| Définir les droits, les profils et la matrice d'une application | ✔ **Paramétrage** | ✔ | |
| Décrire l'architecture, construire, déployer, exposer | ✔ uniquement | | |
| Gérer bases, buckets, variables, secrets, sauvegardes | ✔ uniquement | | |
| Lire le journal d'audit | ✔ **Audit Logs** | ✔ `GET /api/audit-logs` | |
| Analyser un fichier, stocker des données de santé, encaisser un paiement | | ✔ | |
| Lire les thèmes, langues et documents légaux de l'application | | ✔ | |

L'hébergement se pilote **uniquement depuis la console** : il n'existe pas d'API publique d'hébergement pour les clients.

### Ce que l'API publique garantit

- **Le périmètre vient du jeton.** L'organisation, l'application et l'environnement sont lus dans le jeton ou la clé, jamais dans la requête. Une clé API est bornée à son client, son réseau ou son application.
- **Une application, un jeton.** Un jeton émis pour une autre application est refusé.
- **Des erreurs au même format** :

```json
{
  "statusCode": 403,
  "message": "Droit applicatif requis : invitations.create",
  "error": "Forbidden",
  "timestamp": "2026-10-23T09:30:00.000Z",
  "path": "/api/invitations"
}
```

- **Des limites de débit par adresse IP** : 10 requêtes par seconde, 100 par minute, 1 000 par heure. Au-delà, l'API répond `429`.

### La documentation, aussi par API

Cette documentation se consulte depuis votre assistant IA, par le serveur MCP `https://docs.wakastart.app/api/mcp`, et chaque page existe en Markdown.

## Exemples

**Une clinique qui ajoute un soignant.** Le cadre de santé l'invite depuis l'écran d'administration de votre application ; votre back appelle `POST /api/invitations` avec le jeton du cadre. La console n'intervient pas.

**Une mise en production.** Le développeur construit l'image et la déploie dans l'environnement de production depuis la console. Aucune API n'est appelée.

**Une synchronisation nocturne.** Le serveur RH d'un client lit chaque nuit la liste des utilisateurs avec une clé API `sk_…` limitée à son organisation.

## Pour aller plus loin

- [Visite de la console](/v1.0/demarrer/visite-de-la-console) : la carte des menus.
- [Référence API](/v1.0/reference-api) : URL de base, conventions et endpoints.
- [Clés API](/v1.0/cles-api) : authentifier vos serveurs.
- [Discovery](/v1.0/concepts/discovery) : la porte de la connexion.
