Clés publiques et privées

Chaque organisation dispose d’une clé publique et de 20 clés privées actives au maximum. Vous les trouvez sur la page Sécurité, dans les sections Clé publique et Clés privées. Les propriétaires, les administrateurs et les développeurs peuvent les voir ; seuls les propriétaires et les administrateurs peuvent créer, révoquer et renouveler des clés.

	Clé publique	Clé privée
Format	`pk_…`	`sk_…`
Secrète ?	Non – elle est visible dans le code source de votre page	Oui – comme un mot de passe
À utiliser dans	les navigateurs, les applications mobiles, les sites statiques	les serveurs, les fonctions serverless, la CI
Envoyée comme	`user_id` dans le corps ou en-tête `X-Frontmail-Public-Key`	en-tête `Authorization: Bearer sk_…` ou `accessToken` dans le corps
Vérification de l’origine	✓ doit correspondre aux domaines autorisés ; sans `Origin`, il faut Autoriser les applications mobiles	un en-tête `Origin` est refusé (`private_key_in_browser`), sauf autorisation
Turnstile	✓ quand le modèle l’exige	ignoré
Rate limits	par organisation, par IP, par clé	par organisation, par clé
Endpoints	`send`, `send-form`, `uploads`, `messages/:id` (avec jeton de statut)	tous, y compris `send-batch`, `history`, `templates`

Clé publique

La clé publique ne fait qu’identifier votre organisation. N’importe qui peut la copier depuis votre site : c’est pourquoi les requêtes qui l’utilisent sont vérifiées (origine, signaux de bot, débit) – et pourquoi les modèles ne peuvent pas utiliser de destinataires dynamiques sans votre autorisation explicite. Un client avec clé publique ne peut lire que le statut de ses propres messages, grâce au status_token renvoyé par send (envoyé dans l’en-tête X-Frontmail-Status-Token).

Clés privées

Les clés privées contournent les vérifications propres aux navigateurs : elles ne doivent donc jamais se retrouver dans un navigateur. Usages typiques : envoi depuis votre backend, le SDK Node, les envois groupés, la lecture de l’historique et npx frontmail types.

Créez-en une avec Nouvelle clé privée. Elle n’est affichée qu’une seule fois – copiez-la et confirmez avec Je l’ai mise en lieu sûr. Frontmail ne conserve qu’un hash et les quatre derniers caractères.
Donnez un nom à chaque clé (p. ex. « Backend de production », « CI ») pour savoir où elle est utilisée – la colonne Dernière utilisation indique quand chaque clé a servi pour la dernière fois.
L’option Autoriser l’API par clé privée (Sécurité → Protection contre les abus) permet de désactiver complètement l’accès par clé privée pour l’organisation si vous n’envoyez que depuis des navigateurs ; les requêtes avec clé privée échouent alors avec 403 forbidden.
Les requêtes avec clé privée qui portent un en-tête Origin – c’est-à-dire qui viennent d’une page web – échouent avec 403 private_key_in_browser. Cela vaut aussi pour le champ accessToken du corps (à la manière d’EmailJS) et pour les endpoints de lecture. Les serveurs n’envoient pas d’Origin, le code côté serveur n’est donc pas concerné. Uniquement si vous avez vraiment besoin d’une clé privée dans un navigateur (un outil d’administration interne, jamais une page publique), activez Autoriser les clés privées dans les navigateurs (Sécurité → Protection contre les abus, désactivé par défaut).

Renouvellement

Clés privées : créez une nouvelle clé, déployez-la sur vos serveurs, vérifiez que la Dernière utilisation de l’ancienne clé ne change plus, puis cliquez sur Révoquer pour l’ancienne clé. La révocation est immédiate ; les requêtes avec une clé révoquée échouent avec invalid_private_key.

Clé publique : cliquez sur Renouveler la clé dans la section Clé publique. Vous obtenez immédiatement une nouvelle clé ; l’ancienne continue de fonctionner pendant une période de grâce de 24 heures pour vous laisser redéployer votre site, puis elle échoue avec invalid_public_key. Renouvelez la clé publique si vous constatez des abus malgré les domaines autorisés et Turnstile, ou si vous déplacez une application vers une nouvelle organisation.

La création, la révocation et le renouvellement des clés sont enregistrés dans le journal d’audit.