# Référence API

> URL de base, environnements, authentification et liste des domaines de l'API publique Wakastart et de Discovery.

Cette référence décrit les deux services HTTP que votre application et vos serveurs appellent : l'API publique de Wakastart, qui gère l'organisation de vos clients, leurs utilisateurs, leurs droits et les modules, et Discovery, qui indique à votre application où connecter ses utilisateurs. Chaque endpoint décrit ici a été vérifié dans le code de la plateforme.

## URL de base

| Service | URL de base | Authentification |
|---|---|---|
| API publique | `https://api.wakastart.app/api` | Jeton Keycloak, jeton enrichi ou clé API (voir [Authentification](/v1.0/reference-api/authentification-api)) |
| Discovery | `https://discovery.wakastart.app` | Aucune : le service est public |

Tous les chemins de l'API publique commencent par `/api`. Les exemples de cette référence écrivent l'URL complète, par exemple `https://api.wakastart.app/api/me`.

```bash
curl -s https://api.wakastart.app/api/healthz
```

Réponse attendue :

```json
{
  "status": "ok",
  "timestamp": "2026-10-23T09:12:44.512Z",
  "uptime": 86400,
  "service": "ws-back-api",
  "version": "1.0.0"
}
```

## Environnements

Une seule URL de base sert les trois [environnements](/v1.0/glossaire#environnement) de votre application, `dev`, `staging` et `prod`. L'API déduit l'environnement de l'appel :

- d'un jeton Keycloak ou d'un [jeton enrichi](/v1.0/glossaire#jeton-enrichi) : l'environnement de la session, porté par le jeton lui-même ;
- d'une [clé API](/v1.0/glossaire#clé-api) : l'environnement auquel la clé est liée à sa création.

Les données renvoyées suivent cet environnement. Par exemple, `GET /api/me` renvoie le profil que l'utilisateur possède dans l'environnement de sa session.

Chaque environnement a en revanche sa propre instance [Keycloak](/v1.0/glossaire#keycloak) : `https://auth.wakastart.app` en production, `https://auth-staging.wakastart.app` en staging et `https://auth-dev.wakastart.app` en développement. Votre application ne code jamais cette adresse en dur : elle la lit dans sa variable `KEYCLOAK_URL`, posée par environnement, ou dans la réponse de [Discovery](/v1.0/reference-api/discovery).

## Lire cette référence

Chaque page couvre un domaine et suit le même ordre : une description, les objets du domaine avec leurs champs, puis une section par endpoint. Une section d'endpoint indique :

- la méthode et le chemin ;
- **l'accès requis** : le [niveau d'administration](/v1.0/glossaire#niveau-dadministration) minimal de l'appelant et, le cas échéant, le [droit applicatif](/v1.0/glossaire#droit-applicatif) exigé, par exemple `users.read` ;
- les paramètres de chemin, de requête et de corps, avec leur type, leurs contraintes et leur valeur par défaut ;
- un exemple cURL, parfois suivi d'un exemple TypeScript, puis la réponse attendue ;
- les codes d'erreur propres à l'endpoint. Les erreurs communes à toute l'API sont décrites dans [Codes d'erreur](/v1.0/codes-d-erreur).

Les niveaux d'administration s'écrivent dans l'API avec leur code : `PARTNER_ADMIN` (Propriétaire), `APP_ADMIN` (Administrateur d'applications), `NETWORK_ADMIN` (Administrateur réseau), `CUSTOMER_ADMIN` (Administrateur client), `USER` (Utilisateur) et `NONE`. Un niveau inclut tous les niveaux inférieurs.

:::note
L'hébergement (environnements, services, builds, bases de données, domaines) se pilote depuis la console Wakastart : l'API publique n'expose pas ces opérations. La création d'une application est réservée à l'équipe Wakastart : votre application est créée par Wakastart ; contactez-nous pour en ouvrir une.
:::

## Domaines

::::cards{cols=3}
:::card{title="Authentification" href="/v1.0/reference-api/authentification-api" icon="KeyRound"}
Envoyer un jeton Keycloak, un jeton enrichi ou une clé API.
:::
:::card{title="Conventions" href="/v1.0/reference-api/conventions" icon="Braces"}
Format JSON, erreurs, pagination, filtres, limites de débit et CORS.
:::
:::card{title="Discovery" href="/v1.0/reference-api/discovery" icon="Search"}
Obtenir l'adresse de connexion Keycloak à partir de l'URL de votre front.
:::
:::card{title="Jeton et /me" href="/v1.0/reference-api/jeton-et-me" icon="BadgeCheck"}
Lire l'utilisateur connecté, enrichir un jeton, vérifier une autorisation.
:::
:::card{title="Organisations" href="/v1.0/reference-api/organisations" icon="Building2"}
Réseaux et clients de votre application.
:::
:::card{title="Utilisateurs" href="/v1.0/reference-api/utilisateurs" icon="Users"}
Créer, modifier, désactiver et importer des utilisateurs.
:::
:::card{title="Équipes" href="/v1.0/reference-api/equipes" icon="UsersRound"}
Regrouper des utilisateurs et gérer leurs niveaux d'équipe.
:::
:::card{title="Droits et profils" href="/v1.0/reference-api/droits-et-profils" icon="ShieldCheck"}
Catalogue de droits, profils et attribution par environnement.
:::
:::card{title="Invitations" href="/v1.0/reference-api/invitations" icon="Mail"}
Inviter un utilisateur, suivre et accepter une invitation.
:::
:::card{title="Clés API" href="/v1.0/reference-api/cles-api" icon="KeySquare"}
Format, portée et usage d'une clé API.
:::
:::card{title="Audit" href="/v1.0/reference-api/audit" icon="ScrollText"}
Lire le journal d'audit de votre organisation.
:::
:::card{title="Applications" href="/v1.0/reference-api/applications" icon="AppWindow"}
Fiche de l'application et fonctionnalités activables.
:::
:::card{title="Contenus de l'application" href="/v1.0/reference-api/contenus-application" icon="Palette"}
Thèmes, langues, traductions, branding et configuration au démarrage.
:::
:::card{title="Antivirus" href="/v1.0/reference-api/antivirus" icon="ShieldAlert"}
Faire analyser un fichier et recevoir le résultat.
:::
:::card{title="HDS" href="/v1.0/reference-api/hds" icon="HeartPulse"}
Coffres, documents et partages de données de santé.
:::
:::card{title="Paiements" href="/v1.0/reference-api/paiements" icon="CreditCard"}
Faire payer vos utilisateurs avec Stripe Checkout.
:::
:::card{title="Crédits" href="/v1.0/reference-api/credits" icon="Coins"}
Acheter un pack de crédits et comprendre les débits.
:::
:::card{title="Documents légaux" href="/v1.0/reference-api/documents-legaux" icon="FileText"}
Lire et rendre les CGU, CGV et documents RGPD de l'application.
:::
::::

## Ressources

- [Codes d'erreur](/v1.0/codes-d-erreur) : chaque statut HTTP et les messages métier fréquents.
- [Limites et quotas](/v1.0/limites) : limites de débit, tailles maximales et valeurs par défaut.
- [Outils pour assistants IA](/v1.0/outils-ia) : interroger cette documentation depuis Claude, Cursor ou un autre client MCP.
- [Notes de version](/v1.0/notes-de-version) : évolutions de la plateforme et de sa documentation.
