Pour les intégrations machine-à-machine (scripts, serveurs, MCP), Puwapi propose des clés API liées à une organisation et à un module — sans utilisateur ni JWT.
Quatre modules exposent aujourd'hui des clés API tenant : Knowledge, Send, Work et le Hub (CRM). Le même patron s'applique à tous.
Créer une clé¶
Depuis le Hub (interface), section du module → Clés API → créer une clé, en choisissant un scope :
- read — lecture seule.
- write — lecture + écriture (création/modification).
La clé complète n'est affichée qu'une seule fois à la création. En base, seul un hachage (SHA-256) est conservé — Puwapi ne peut pas vous la re-montrer.
Côté API (avec JWT) :
| Module | Préfixe de clé | Route de gestion |
|---|---|---|
| Knowledge | pkk_live_… | /api/knowledge/keys |
| Send | psk_live_… | /api/send/keys |
| Work | pwk_live_… | /api/work/keys |
| Hub (CRM) | phk_live_… | /api/hub/keys |
Verbes : GET, POST, DELETE {id}.
Corps de création : { "label": "mon-intégration", "scope": "write" }.
Utiliser une clé¶
Envoyez-la dans l'en-tête X-Server-API-Key :
curl https://knowledge.api.puwapi.com/api/public/knowledge/spaces \
-H "X-Server-API-Key: pkk_live_xxx"
Un intergiciel (ApiKeyMiddleware) monté avant la résolution du tenant lit la clé,
pose l'organisation + l'utilisateur créateur, et applique le scope : une clé read qui
tente un POST/PATCH/DELETE reçoit 403.
{ "error": "Cette clé est en lecture seule (scope read)." }
Surfaces d'intégration¶
Les clés API donnent accès à des routes d'intégration dédiées, distinctes des routes membres :
- Knowledge :
api/public/knowledge/*(espaces, collections, articles, recherche). - Send :
api/public/send/*(e-mail, SMS, WhatsApp). - Work :
api/public/work/*(projets, items, imports bulk). - Hub (CRM) :
api/public/hub/*(contacts, imports bulk de contacts et deals).
⚠️ À ne pas confondre avec les surfaces publiques anonymes (api/knowledge/public/*,
lecture par slug) qui n'exigent aucune clé.
Serveurs MCP¶
Deux serveurs MCP s'appuient sur ces clés :
@puwapi/knowledge-mcp(clépkk_live_…) — 20 outils de gestion documentaire ; voir Piloter Knowledge avec le serveur MCP.@puwapi/mcp(cléspwk_live_…+phk_live_…) — imports et gestion Work + CRM ; voir Importer des données avec le serveur MCP Puwapi.
Sécurité¶
- Traitez une clé write comme un mot de passe : elle peut écrire dans votre organisation.
- Révoquez immédiatement une clé compromise (
DELETE), puis recréez-en une. - Préférez le scope minimal :
readsi vous ne faites que lire.