Klucze i uwierzytelnianie

Klucz publiczny i klucz tajny

Klucz publiczny przekazywany jest w adresie URL jako ?key=. Jest publiczny z założenia: znajduje się w kodzie źródłowym Twojej strony i działa tylko z originów wymienionych przy nim. Klucz tajny przekazywany jest jako Authorization: Bearer <key> i jest wyłącznie dla Twojego serwera. Przeglądarka nawet nie może go wysłać do usługi: Authorization nie ma na liście dozwolonych nagłówków CORS.

Dozwolone originy

Każdy klucz publiczny ma listę do 20 originów: schemat, host i port dokładnie tak, jak wysyła je przeglądarka, np. https://shop.example.com. Żądanie z dowolnego innego origin jest odrzucane z 403 origin_not_allowed, łącznie z żądaniem preflight, a usługa nigdy nie odpowiada z Access-Control-Allow-Origin: *. Lista jest sygnałem, nie uwierzytelnianiem: prawdziwą obroną są cena liczona po stronie serwera i limity zapytań.

Klucze testowe

Działający sklep może utworzyć do 3 kluczy testowych (pk_test_…, sk_test_…). Klucz testowy wycenia na podstawie Twojego najnowszego zatwierdzonego szkicu, więc zmianę możesz wypróbować przed jej publikacją. Nie jest rozliczany, jego zamówienia nie wysyłają webhooka ani e-maila, a po 30 dniach wygasa. Test i produkcja nigdy się nie mieszają: wycena testowa weryfikuje się tylko z testowym kluczem tajnym, zamówienie testowe jest widoczne tylko dla klucza testowego, a klucz produkcyjny nigdy go nie widzi. Klucz testowy może mieć http://localhost jako origin.

Token projektu

Zapisane projekty są przypisane do kupującego, nie do konta. Pierwsze POST /cfg/v1/projects wydaje losowy token (cfgpt_…) i zwraca go tylko raz; osadzony konfigurator go przechowuje i wysyła jako X-Cfg-Project-Token przy każdym kolejnym wywołaniu projektu. Token innego kupującego, klucz innego sklepu i nieznany identyfikator odpowiadają tak samo: 404.

Rotacja bez przestojów

Rotację wykonuje się w konsoli, a każdy rodzaj ma okres nakładania się, by nic się nie zepsuło podczas przełączania.

• Klucz publiczny: nowy klucz zachowuje tę samą listę originów; stary działa domyślnie jeszcze 168 godz. (maksymalnie 720).
• Klucz tajny: pokazywany jeden raz; stary klucz domyślnie nadal uwierzytelnia przez 24 godz. (maksymalnie 720).
• Klucz podpisywania wycen: nowy klucz podpisuje od teraz; wyceny podpisane starym kluczem nadal się weryfikują i można je jeszcze zamawiać przez maksymalnie 31 dni.
• Sekret webhooka: podczas przełączania oba sekrety podpisują każdą dostawę przez 7 dni, jako dwie wartości v1=, więc Twój odbiornik może przyjąć którąkolwiek.

Co nigdy nie trafia do przeglądarki

Klucz tajny i sekret webhooka (whsec_…). Trzymaj je w środowisku swojego serwera, nigdy na stronie, w repozytorium ani w logu. Jeśli któryś wycieknie, zrotuj go w konsoli.