Verejný a súkromný kľúč

Každá organizácia má jeden verejný kľúč (public key) a až 20 aktívnych súkromných kľúčov (private keys). Nájdete ich na stránke Zabezpečenie v častiach Verejný kľúč a Súkromné kľúče. Vidia ich vlastník, administrátori a vývojári; vytvárať, zneplatňovať a vymieňať ich môžu len vlastník a administrátori.

	Verejný kľúč	Súkromný kľúč
Formát	`pk_…`	`sk_…`
Tajný?	Nie – je vidieť v zdrojovom kóde stránky	Áno – ako heslo
Kde použiť	Prehliadače, mobilné aplikácie, statické weby	Servery, serverless funkcie, CI
Ako poslať	v tele ako `user_id` alebo v hlavičke `X-Frontmail-Public-Key`	v hlavičke `Authorization: Bearer sk_…` alebo v tele ako `accessToken`
Kontrola domény	✓ musí zodpovedať povoleným doménam; bez `Origin` len s Povoliť mobilné aplikácie	hlavička `Origin` sa odmietne (`private_key_in_browser`), pokiaľ to nepovolíte
Turnstile	✓ ak ho šablóna vyžaduje	preskakuje sa
Rate limity	na organizáciu, na IP adresu, na kľúč	na organizáciu, na kľúč
Endpointy	`send`, `send-form`, `uploads`, `messages/:id` (so status tokenom)	všetky, vrátane `send-batch`, `history`, `templates`

Verejný kľúč

Verejný kľúč len identifikuje vašu organizáciu. Ktokoľvek si ho môže z vášho webu skopírovať, a preto sa pri požiadavkách s ním kontroluje doména, signály botov a rýchlosť – a preto šablóny nemôžu používať dynamických príjemcov, pokiaľ to výslovne nepovolíte. Klient s verejným kľúčom si môže prečítať stav len svojich vlastných správ, a to pomocou status_token, ktorý vracia send (posiela sa v hlavičke X-Frontmail-Status-Token).

Súkromné kľúče

Súkromné kľúče obchádzajú kontroly určené pre prehliadač, takže sa do prehliadača nikdy nesmú dostať. Typické použitie: odosielanie z vášho backendu, Node SDK, hromadné odosielanie, čítanie histórie a npx frontmail types.

Vytvoríte ho tlačidlom Nový súkromný kľúč. Zobrazí sa len raz – skopírujte ho a potvrďte Bezpečne som si ho uložil. Frontmail ukladá iba jeho hash a posledné štyri znaky.
Každý kľúč pomenujte (napr. „Produkčný backend“, „CI“), aby ste vedeli, kde sa používa – stĺpec Naposledy použitý ukazuje, kedy bol ktorý kľúč naposledy použitý.
Prepínačom Povoliť API so súkromným kľúčom (Zabezpečenie → Ochrana pred zneužitím) môžete prístup so súkromným kľúčom pre celú organizáciu úplne vypnúť, ak odosielate len z prehliadačov; požiadavky so súkromným kľúčom potom zlyhajú s 403 forbidden.
Požiadavky so súkromným kľúčom, ktoré nesú hlavičku Origin – teda prichádzajú z webovej stránky –, zlyhajú s 403 private_key_in_browser. Platí to aj pre pole accessToken v tele (kompatibilita s EmailJS) a pre čítacie endpointy. Servery Origin neposielajú, takže serverového kódu sa to netýka. Len ak súkromný kľúč v prehliadači naozaj potrebujete (interný administračný nástroj, nikdy verejná stránka), zapnite Povoliť súkromné kľúče v prehliadačoch (Zabezpečenie → Ochrana pred zneužitím, predvolene vypnuté).

Výmena kľúčov

Súkromné kľúče: vytvorte nový kľúč, nasaďte ho na svoje servery, overte, že sa pri starom kľúči prestal meniť údaj Naposledy použitý, a potom starý kľúč zneplatnite tlačidlom Zneplatniť. Zneplatnenie platí okamžite; požiadavky so zneplatneným kľúčom zlyhajú s chybou invalid_private_key.

Verejný kľúč: v časti Verejný kľúč kliknite na Vymeniť kľúč. Nový kľúč dostanete okamžite; starý ešte 24 hodín funguje (prechodné obdobie), aby ste stihli znova nasadiť web, a potom začne zlyhávať s chybou invalid_public_key. Verejný kľúč vymeňte, keď aj napriek povoleným doménam a Turnstile zaznamenáte zneužitie, alebo keď presúvate aplikáciu do inej organizácie.

Vytvorenie, zneplatnenie aj výmena kľúčov sa zaznamenávajú do auditného záznamu.