Aller au contenu principal

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ête Authorization.
  • organizations : les organisations de ce compte, avec votre rôle dans chacune. La valeur id est à renvoyer en en-tête X-Organization-Id sur 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/refresh puis 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.