Authentification API
L'API CRMarket utilise des tokens JWT pour l'authentification. Toutes les requêtes doivent inclure un token valide dans l'en-tête Authorization.
Base URL
https://crm.websimplicite.fr/api/v1
En développement local :
http://localhost:4000/api/v1
Obtenir un token
Via l'API (programmatique)
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "votre@email.com",
"password": "votre_mot_de_passe"
}
Réponse :
{
"data": {
"token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...",
"organizations": [
{ "id": "3f1c9e52-...", "name": "Mon organisation", "role": "admin" }
]
}
}
token: token d'accès, valide 1 heure. À porter en en-têteAuthorization.organizations: les organisations de ce compte, avec votre rôle dans chacune. La valeuridest à renvoyer en en-têteX-Organization-Idsur les requêtes suivantes.
Le refresh token n'est pas dans le corps de la réponse. Il est posé dans un cookie
refresh_token HttpOnly, SameSite=Strict, limité au chemin /api/v1/auth et valide
30 jours. Un client JavaScript ne peut donc pas le lire — c'est voulu. En dehors d'un
navigateur, conservez ce cookie et renvoyez-le sur /auth/refresh.
Rafraîchir le token
Avant expiration du token d'accès, obtenez-en un nouveau. Aucun en-tête
Authorization n'est attendu : le refresh token est lu dans le cookie.
POST /api/v1/auth/refresh
Cookie: refresh_token=eyJ...
Réponse :
{
"data": {
"token": "eyJ...",
"user": { "id": "7d2a1b04-...", "email": "votre@email.com" },
"organizations": [{ "id": "3f1c9e52-...", "name": "Mon organisation", "role": "admin" }]
}
}
Le refresh token est à usage unique : chaque appel à /auth/refresh en génère un
nouveau et repose le cookie. Un client hors navigateur doit donc remplacer le cookie
conservé à chaque appel.
Utiliser le token
Incluez le token d'accès dans l'en-tête Authorization, et l'organisation visée dans
X-Organization-Id — un compte peut appartenir à plusieurs organisations, et c'est cet
en-tête qui tranche :
GET /api/v1/contacts
Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9...
X-Organization-Id: 3f1c9e52-0b3d-4a71-9f0e-2c5d8a1b7e44
Tous les identifiants de l'API sont des UUID.
Clés API (MCP)
Pour les intégrations avec des outils LLM via le Model Context Protocol (MCP), CRMarket propose des clés API à portée limitée. Elles sont différentes des tokens JWT et adaptées aux accès programmatiques longue durée.
Créer une clé API
Allez dans Paramètres → Clés API → Créer une clé.
Définissez les portées (scopes) :
| Scope | Permissions |
|-------|-------------|
| contacts:read | Lire les contacts, segments et listes de suppression |
| contacts:write | Créer et modifier des segments |
| campaigns:read | Lire les campagnes et prévisualiser leur audience |
| campaigns:write | Créer des templates et des campagnes |
| analytics:read | Lire les analytics |
| knowledge:read | Lire la base de connaissance de marque |
| knowledge:write | Écrire dans la base de connaissance de marque |
Utiliser une clé API
GET /api/v1/contacts
X-CRMarket-API-Key: umk_live_abc123def456...
Deux autres formes sont acceptées, pour les clients qui ne peuvent pas poser d'en-tête personnalisé — un connecteur MCP, typiquement :
Authorization: Bearer umk_live_abc123def456...
X-Unimail-API-Key: umk_live_abc123def456...
La troisième est conservée pour compatibilité ; préférez les deux premières.
Ne jamais exposer votre clé API côté client (JavaScript navigateur). Utilisez uniquement depuis un serveur. Si une clé est compromise, révoquez-la immédiatement depuis Paramètres → Clés API.
Codes d'erreur
| Code HTTP | Signification |
|-----------|--------------|
| 400 | Requête invalide (corps JSON malformé, champ manquant) |
| 401 | Token manquant ou expiré |
| 403 | Token valide mais permissions insuffisantes |
| 404 | Ressource introuvable |
| 422 | Données invalides (email déjà utilisé, format incorrect) |
| 429 | Trop de requêtes (rate limiting) |
| 500 | Erreur serveur |
Format des erreurs
{
"error": {
"code": "unauthorized",
"message": "Token expiré. Utilisez le refresh token pour en obtenir un nouveau.",
"details": {}
}
}
details est toujours présent. Sur une erreur de validation (422), il porte les erreurs
par champ :
{
"error": {
"code": "validation_error",
"message": "Invalid parameters.",
"details": { "email": ["has invalid format"] }
}
}
Quotas
Les quotas se cumulent : un appel à un endpoint IA consomme à la fois le quota général et le quota IA.
| Portée | Plafond | Compté par | | --- | --- | --- | | API authentifiée | 300 requêtes / minute | organisation | | Endpoints qui appellent un modèle | 30 requêtes / heure | organisation | | Serveur MCP | 120 requêtes / minute | organisation | | Connexion, inscription, mot de passe oublié | 10 requêtes / minute | adresse IP | | Routes publiques (double opt-in, préférences, formulaires, OAuth) | 60 lectures et 10 écritures / minute | adresse IP | | Soumission d'un formulaire d'inscription | 5 / 10 min par IP, 100 / 10 min par formulaire | IP et formulaire |
La soumission de formulaire est la seule à porter deux compteurs : un plafond par IP n'arrête pas une attaque distribuée, un plafond par formulaire ne distingue pas l'abuseur isolé. Aucun des deux ne remplace l'autre.
Au-delà, la réponse est un 429 avec l'en-tête Retry-After en secondes. Trois en-têtes
accompagnent chaque réponse et évitent d'avoir à deviner où vous en êtes :
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1760108400
X-RateLimit-Reset est un horodatage Unix.
Clients
Il n'existe pas de SDK officiel : l'API se consomme en HTTP, avec le client de votre langage. Les exemples de cette documentation sont en HTTP brut pour cette raison.
Deux détails à prévoir dans un client maison :
- le rafraîchissement — sur un
401, appelez/auth/refreshpuis rejouez la requête une seule fois ; une boucle sur un refresh qui échoue est le piège classique ; - l'en-tête
X-Organization-Id— à poser sur chaque requête, sans quoi l'organisation n'est pas résolue.