Chiavi pubbliche e private

Ogni organizzazione ha una chiave pubblica e fino a 20 chiavi private attive. Le trovi nella pagina Sicurezza, nelle sezioni Chiave pubblica e Chiavi private. Proprietari, admin e sviluppatori possono vederle; solo proprietari e admin possono creare, revocare e ruotare le chiavi.

	Chiave pubblica	Chiave privata
Formato	`pk_…`	`sk_…`
Segreta?	No – è visibile nel sorgente della pagina	Sì – come una password
Dove usarla	Browser, app mobile, siti statici	Server, funzioni serverless, CI
Come inviarla	body `user_id` o header `X-Frontmail-Public-Key`	header `Authorization: Bearer sk_…` o body `accessToken`
Controllo dell’origine	✓ deve corrispondere ai domini consentiti; senza `Origin` serve Consenti app mobile	un header `Origin` viene rifiutato (`private_key_in_browser`), salvo autorizzazione
Turnstile	✓ quando il modello lo richiede	saltato
Rate limit	per organizzazione, per IP, per chiave	per organizzazione, per chiave
Endpoint	`send`, `send-form`, `uploads`, `messages/:id` (con status token)	tutti, inclusi `send-batch`, `history`, `templates`

Chiave pubblica

La chiave pubblica identifica soltanto la tua organizzazione. Chiunque può copiarla dal tuo sito: per questo le richieste firmate con essa vengono verificate per origine, segnali di bot e frequenza, e per questo i modelli non possono usare destinatari dinamici, a meno che tu non lo consenta esplicitamente. Un client con chiave pubblica può leggere lo stato solo dei propri messaggi, usando lo status_token restituito da send (inviato nell’header X-Frontmail-Status-Token).

Chiavi private

Le chiavi private saltano i controlli pensati per il browser, quindi non devono mai finire in un browser. Usi tipici: invio dal tuo backend, l’SDK Node, invii in batch, lettura della cronologia e npx frontmail types.

Creane una con Nuova chiave privata. Viene mostrata una sola volta: copiala e conferma con L’ho salvata in un posto sicuro. Frontmail conserva solo un hash e gli ultimi quattro caratteri.
Dai a ogni chiave un nome (ad es. «Backend di produzione», «CI») per sapere dove viene usata: la colonna Ultimo utilizzo mostra quando ciascuna chiave è stata usata l’ultima volta.
L’interruttore Consenti l’API con chiave privata (Sicurezza → Protezione dagli abusi) può disattivare completamente l’accesso con chiave privata per l’organizzazione, se invii solo dai browser; le richieste con chiave privata falliscono allora con 403 forbidden.
Le richieste con chiave privata che portano un header Origin – cioè che arrivano da una pagina web – falliscono con 403 private_key_in_browser. Vale anche per il campo accessToken nel body in stile EmailJS e per gli endpoint di lettura. I server non inviano Origin, quindi il codice lato server non è interessato. Solo se hai davvero bisogno di una chiave privata in un browser (uno strumento di amministrazione interno, mai una pagina pubblica) attiva Consenti chiavi private nei browser (Sicurezza → Protezione dagli abusi, disattivato per impostazione predefinita).

Rotazione

Chiavi private: crea una nuova chiave, distribuiscila sui tuoi server, verifica che l’Ultimo utilizzo della vecchia chiave smetta di cambiare, poi fai Revoca sulla vecchia chiave. La revoca è immediata; le richieste con una chiave revocata falliscono con invalid_private_key.

Chiave pubblica: fai clic su Ruota chiave nella sezione Chiave pubblica. Ricevi subito una nuova chiave; quella vecchia continua a funzionare per un periodo di tolleranza di 24 ore, così puoi ripubblicare il sito, poi fallisce con invalid_public_key. Ruota la chiave pubblica quando noti abusi nonostante i domini consentiti e Turnstile, oppure quando sposti un’app in una nuova organizzazione.

Creazione, revoca e rotazione delle chiavi vengono registrate nel registro attività.