Authentification headless : relier WordPress à HubSpot sans exposer le CRM

Une clé d’API privée HubSpot capable de créer et modifier des contacts n’a strictement rien à faire dans le code JavaScript livré au navigateur, aussi tentant que cela puisse paraître pour simplifier un formulaire de contact. Pourtant, cette erreur reste fréquente sur les projets headless pressés par un délai serré : un appel direct depuis le composant de formulaire vers l’API HubSpot, avec la clé en dur dans une variable d’environnement publique.

Trois approches permettent d’éviter cet écueil sur un projet WordPress headless connecté à HubSpot : le proxy serveur classique, le jeton à portée strictement réduite, et la fonction edge. Chacune a ses compromis en matière de latence, de complexité opérationnelle et de niveau de contrôle métier possible avant l’écriture dans le CRM.

Approche 1 : le proxy WordPress

Le formulaire front poste vers un endpoint REST personnalisé de WordPress, qui valide les données puis relaie la requête vers l’API HubSpot avec la clé privée, jamais exposée au-delà du serveur :

add_action('rest_api_init', function () {
    register_rest_route('crm/v1', '/contact', [
        'methods' => 'POST',
        'callback' => 'creer_contact_hubspot',
        'permission_callback' => '__return_true',
        'args' => [
            'email' => ['required' => true, 'validate_callback' => 'is_email'],
        ],
    ]);
});

function creer_contact_hubspot(WP_REST_Request $request) {
    $email = sanitize_email($request->get_param('email'));

    $reponse = wp_remote_post('https://api.hubapi.com/crm/v3/objects/contacts', [
        'headers' => ['Authorization' => 'Bearer ' . HUBSPOT_CLE_PRIVEE, 'Content-Type' => 'application/json'],
        'body' => wp_json_encode(['properties' => ['email' => $email]]),
    ]);

    return new WP_REST_Response(['statut' => 'ok'], 200);
}

Cette approche centralise la logique métier au même endroit que le reste du contenu WordPress, ce qui facilite l’audit, mais ajoute un aller-retour réseau supplémentaire entre le front et le serveur WordPress avant même d’atteindre HubSpot.

Approche 2 : le jeton à portée réduite

Plutôt qu’une clé privée complète, HubSpot permet de générer des jetons d’application privée avec des portées (scopes) précisément délimitées. Un jeton limité au seul scope crm.objects.contacts.write, sans droit de lecture ni de suppression, réduit considérablement l’impact d’une éventuelle fuite. Cette approche ne dispense cependant pas d’un relais serveur : un jeton, même restreint en portée, reste une clé secrète qui ne doit jamais transiter vers le navigateur.

Approche 3 : la fonction edge

Sur un front Next.js hébergé chez Vercel, une fonction edge peut remplir le même rôle que le proxy WordPress, mais avec une latence réduite grâce à son exécution au plus près du visiteur :

export const config = { runtime: 'edge' };

export default async function handler(request) {
  const { email } = await request.json();

  if (!email || !email.includes('@')) {
    return new Response(JSON.stringify({ erreur: 'email invalide' }), { status: 400 });
  }

  const reponse = await fetch('https://api.hubapi.com/crm/v3/objects/contacts', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.HUBSPOT_TOKEN}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ properties: { email } }),
  });

  return new Response(await reponse.text(), { status: reponse.status });
}

Cette approche déplace la logique de validation hors de WordPress, ce qui peut créer une divergence si des règles métier similaires existent déjà côté back-office (déduplication, scoring de lead) et doivent être maintenues à deux endroits distincts.

Comparatif des trois approches

Critère	Proxy WordPress	Jeton scope réduit	Fonction edge
Latence ajoutée	Moyenne	Nécessite un relais malgré tout	Faible
Centralisation métier	Forte	Aucune en soi	Faible, logique dupliquée possible
Complexité opérationnelle	Faible	Faible	Moyenne (déploiement edge séparé)

Notre verdict

Le proxy WordPress reste le choix par défaut le plus sûr et le plus simple à maintenir pour la majorité des projets, car il garde la logique métier au même endroit que le reste du contenu. La fonction edge se justifie surtout quand la latence du formulaire devient un enjeu mesuré et documenté, et le jeton à portée réduite doit systématiquement s’ajouter à l’une des deux autres approches, jamais s’y substituer. Dans tous les cas, la configuration marketing de HubSpot elle-même (workflows, scoring) reste un sujet distinct, non traité ici.