L'API Puwapi est REST sur HTTPS, en JSON. Chaque module expose sa propre API, mais toutes suivent les mêmes conventions : même authentification, mêmes codes d'erreur, même isolation par organisation.
Les deux façons de s'authentifier¶
| Contexte | Méthode | En-tête |
|---|---|---|
| Application / utilisateur connecté | JWT émis par l'Identity Hub | Authorization: Bearer <jwt> |
| Intégration serveur / script | Clé API de module | X-Server-API-Key: <clé> |
- Le JWT porte l'utilisateur et son organisation (tenant). Voir Authentification.
- La clé API est liée à une organisation et à un module (ex. Knowledge, Send). Voir Clés API serveur.
Anatomie d'un appel¶
curl https://work.puwapi.com/api/work/items \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json"
# Intégration serveur (clé API Knowledge)
curl https://knowledge.api.puwapi.com/api/public/knowledge/spaces \
-H "X-Server-API-Key: pkk_live_xxx"
Ce qu'il faut retenir¶
- Un module = une base URL. Voir Environnements, domaines et ports.
- Tout est cloisonné par organisation. Vous ne voyez jamais les données d'un autre tenant ; l'isolation est déduite de votre jeton.
- Le gating renvoie 403. Si votre organisation n'a pas le module dans son abonnement,
l'API répond
403. Voir Gating par module. - Les erreurs sont en JSON :
{ "error": "message lisible" }. Voir Conventions REST. - Le temps réel est optionnel : l'API REST suffit ; Convex ne fait qu'accélérer le rafraîchissement des interfaces. Voir Temps réel.
Parcours conseillé¶
- Authentification — obtenir et rafraîchir un JWT.
- Clés API serveur — pour les intégrations sans utilisateur.
- Conventions REST — pagination, erreurs, idempotence.
- La référence du module qui vous intéresse (Work, Forms, IA…).