Klucze publiczne i prywatne

Każda organizacja ma jeden klucz publiczny i do 20 aktywnych kluczy prywatnych. Znajdziesz je na stronie Bezpieczeństwo, w sekcjach Klucz publiczny i Klucze prywatne. Widzą je właściciel, administratorzy i programiści; tworzyć, unieważniać i wymieniać klucze mogą tylko właściciel i administratorzy.

	Klucz publiczny	Klucz prywatny
Format	`pk_…`	`sk_…`
Tajny?	Nie – widać go w kodzie źródłowym strony	Tak – jak hasło
Gdzie używać	Przeglądarki, aplikacje mobilne, strony statyczne	Serwery, funkcje serverless, CI
Jak wysłać	w treści jako `user_id` albo w nagłówku `X-Frontmail-Public-Key`	w nagłówku `Authorization: Bearer sk_…` albo w treści jako `accessToken`
Sprawdzanie domeny	✓ musi pasować do dozwolonych domen; bez `Origin` tylko z Zezwól na aplikacje mobilne	nagłówek `Origin` jest odrzucany (`private_key_in_browser`), chyba że na to zezwolisz
Turnstile	✓ gdy szablon go wymaga	pomijany
Rate limity	na organizację, na IP, na klucz	na organizację, na klucz
Endpointy	`send`, `send-form`, `uploads`, `messages/:id` (ze status tokenem)	wszystkie, w tym `send-batch`, `history`, `templates`

Klucz publiczny

Klucz publiczny tylko identyfikuje twoją organizację. Każdy może go skopiować z twojej strony, dlatego przy żądaniach z nim sprawdzamy domenę, sygnały botów i tempo – i dlatego szablony nie mogą używać dynamicznych odbiorców, dopóki wyraźnie na to nie zezwolisz. Klient z kluczem publicznym może odczytać status tylko swoich własnych wiadomości, za pomocą status_token zwracanego przez send (wysyłanego w nagłówku X-Frontmail-Status-Token).

Klucze prywatne

Klucze prywatne omijają kontrole przeznaczone dla przeglądarek, więc nigdy nie mogą do przeglądarki trafić. Typowe zastosowania: wysyłka z twojego backendu, Node SDK, wysyłki zbiorcze, odczyt historii i npx frontmail types.

Utworzysz go przyciskiem Nowy klucz prywatny. Pokazuje się tylko raz – skopiuj go i potwierdź przyciskiem Zapisałem(-am) go w bezpiecznym miejscu. Frontmail przechowuje tylko jego hash i cztery ostatnie znaki.
Nadaj każdemu kluczowi nazwę (np. „Backend produkcyjny”, „CI”), żeby wiedzieć, gdzie jest używany – kolumna Ostatnio użyty pokazuje, kiedy każdy klucz był ostatnio użyty.
Przełącznikiem Zezwól na API z kluczem prywatnym (Bezpieczeństwo → Ochrona przed nadużyciami) możesz całkowicie wyłączyć dostęp z kluczem prywatnym dla organizacji, jeśli wysyłasz tylko z przeglądarek; żądania z kluczem prywatnym kończą się wtedy błędem 403 forbidden.
Żądania z kluczem prywatnym, które niosą nagłówek Origin – czyli pochodzą ze strony internetowej – kończą się błędem 403 private_key_in_browser. Dotyczy to też pola accessToken w treści (zgodność z EmailJS) i endpointów do odczytu. Serwery nie wysyłają Origin, więc kodu po stronie serwera to nie dotyczy. Tylko jeśli naprawdę potrzebujesz klucza prywatnego w przeglądarce (wewnętrzne narzędzie administracyjne, nigdy publiczna strona), włącz Zezwól na klucze prywatne w przeglądarkach (Bezpieczeństwo → Ochrona przed nadużyciami, domyślnie wyłączone).

Wymiana kluczy

Klucze prywatne: utwórz nowy klucz, wdróż go na swoje serwery, sprawdź, że wartość Ostatnio użyty starego klucza przestała się zmieniać, a potem unieważnij stary klucz przyciskiem Unieważnij. Unieważnienie działa natychmiast; żądania z unieważnionym kluczem kończą się błędem invalid_private_key.

Klucz publiczny: w sekcji Klucz publiczny kliknij Zmień klucz. Nowy klucz dostajesz od razu; stary działa jeszcze przez 24 godziny (okres przejściowy), żeby był czas na ponowne wdrożenie strony, a potem zaczyna zwracać błąd invalid_public_key. Wymień klucz publiczny, gdy mimo dozwolonych domen i Turnstile widzisz nadużycia albo gdy przenosisz aplikację do innej organizacji.

Tworzenie, unieważnianie i wymiana kluczy są zapisywane w dzienniku zdarzeń.