Klucze API — tnea_ i tnsr_¶

NumerologyAPI wykorzystuje dwie rodziny kluczy API. Oba wyglądają podobnie, są generowane w tym samym bezpiecznym formacie 80-znakowym i uwierzytelniają się tym samym nagłówkiem X-API-Key — ale są rozliczane inaczej i przeznaczone dla różnych produktów.

1. Format klucza i bezpieczeństwo¶

Każdy klucz ma dokładnie 80 znaków:

tnea_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
tnsr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• 4-znakowy prefiks określa typ klucza; pozostałe 75 znaków jest generowanych z kryptograficznie bezpiecznego źródła losowego.
• Klucze są przechowywane z hashowaniem SHA-256 po stronie serwera. Klucz w postaci jawnej jest pokazywany tylko raz, w momencie utworzenia.
• Jeśli klucz kiedykolwiek wycieknie, natychmiast go zrotuj w panelu.

2. Klucze platformowe (tnea_)¶

Klucze platformowe to standardowe klucze do integracji NumerologyAPI z Twoim własnym produktem — stronami internetowymi, aplikacjami mobilnymi i usługami serwerowymi.

Uwierzytelnianie¶

Wyślij klucz w każdym żądaniu z nagłówkiem X-API-Key:

curl --request GET \
  --url "https://api.numerologyapi.com/api/v1/life_path?birth_year=1990&birth_month=5&birth_day=15" \
  --header "x-api-key: tnea_YOUR_API_KEY"

Rozliczanie¶

Płatne wywołania /api/v1 są odejmowane z portfela kredytów organizacji (pay-as-you-go). Portfel możesz doładować w dowolnym momencie w panelu.

Reguła kanału: klucze platformowe nie mogą wysyłać nagłówka X-Numora-Client. Jego wysłanie zwraca 403 — nagłówek ten jest zarezerwowany dla kanału desktopowego.

3. Klucze Numora Studio (tnsr_)¶

Klucze Numora Studio uwierzytelniają aplikację desktopową Numora Studio (macOS/Windows) używaną przez praktyków do generowania raportów dla klientów. Są odpowiednikiem kluczy platformowych o identycznym formacie, ale są rozliczane względem limitu planu Numora Studio organizacji zamiast kredytów platformowych.

Dostarczanie¶

Klucz tnsr_ jest tworzony na jeden z dwóch sposobów:

• przez proces logowania w aplikacji desktopowej (strona zgody w przeglądarce dostarcza klucz automatycznie), lub
• ręcznie na stronie Klucze API w panelu (/api-keys).

Sygnatura kanału (wymagana)¶

Każde wywołanie wykonane kluczem tnsr_ musi zawierać nagłówek kanału desktopowego:

Egzekwowanie po stronie serwera:

• klucz tnsr_ bez X-Numora-Client → 403.
• klucz tnea_ z X-Numora-Client → 403.

Rozliczanie¶

• Płatne wywołania /api/v1 odejmują z limitu planu Numora Studio organizacji (jedna wspólna pula dla wszystkich kluczy tnsr_ organizacji).
• Istnieje przełącznik fallbacku kredytowego dla każdego klucza tnsr_: gdy limit planu zostanie wyczerpany, klucz może korzystać z kredytów platformowych organizacji (domyślnie wyłączone).
• Jeśli limit jest wyczerpany i fallback nie jest włączony, wywołania zwracają 429.

Blokada urządzeń (opcjonalna)¶

Klucz tnsr_ może być przypięty do zarejestrowanych urządzeń. Przy włączonej blokadzie każde żądanie musi zawierać X-Numora-Device-Id zarejestrowany w organizacji; niezarejestrowane urządzenia są odrzucane z kodem 403.

Punkty końcowe tylko dla aplikacji desktopowej¶

Niektóre punkty końcowe są zarezerwowane dla kanału desktopowego i zwracają 403 dla kluczy tnea_:

• POST /api/v1/numora/report-bundle — pełny raport klienta w jednym wywołaniu
• POST /api/v1/numora/order — proces zakupu planu/limitu w aplikacji
• POST /api/v1/numora/devices/register — rejestracja instalacji desktopowej
• GET /api/v1/numora/studio-status — salda i liczniki wykorzystania dla aplikacji desktopowej

Wskazówka: płatne odpowiedzi zawierają również nagłówki X-Remaining-Credits i X-Remaining-Tokens, dzięki którym możesz śledzić bieżące salda bez dodatkowych wywołań.

4. Zarządzanie kluczami (Panel)¶

Strona Klucze API w panelu (/api-keys) to centrum sterowania dla obu typów kluczy.

Role: role admin i developer mogą tworzyć klucze i zarządzać nimi. Rola finance nie może tworzyć produkcyjnych kluczy API. Operacje finansowe (zakup planów, doładowania) są ograniczone do ról admin i finance.

Wiele kluczy: organizacje mogą posiadać wiele kluczy obu typów — na przykład po jednym kluczu tnsr_ na praktyka lub na instalację desktopową. Limity są współdzielone w ramach organizacji, więc klucze nigdy nie "konkurują" o własne saldo.

5. Najlepsze praktyki¶

• Traktuj klucze jak hasła. Nigdy nie osadzaj ich w kodzie po stronie klienta, publicznych repozytoriach ani logach.
• Używaj zmiennych środowiskowych lub menedżera sekretów w swoim backendzie.
• Rotuj natychmiast, jeśli klucz został naruszony lub członek zespołu odchodzi.
• Używaj jednego klucza tnsr_ na instalację desktopową, aby uprościć zarządzanie urządzeniami i unieważnianie.
• Włącz blokadę urządzeń dla organizacji o podwyższonych wymogach bezpieczeństwa.
• Monitoruj zużycie w panelu, aby wcześnie wykrywać nieoczekiwane skoki.

6. Częste pytania¶

Czy klucz tnsr_ może wywoływać zwykłe punkty końcowe platformy? Tak. Klucze Numora Studio uwierzytelniają całą powierzchnię /api/v1; te wywołania są rozliczane względem limitu planu Numora Studio.

Czy klucz tnea_ może wywoływać punkty końcowe /numora/* przeznaczone tylko dla aplikacji desktopowej? Nie. Punkty końcowe przeznaczone tylko dla aplikacji desktopowej zwracają 403 dla kluczy platformowych.

Dlaczego otrzymuję 403 podczas wywołań moim kluczem tnsr_? Najprawdopodobniej brakuje nagłówka X-Numora-Client lub identyfikator aplikacji się nie zgadza. Sprawdź, czy każde żądanie zawiera X-Numora-Client: numora-studio/<version>.

Dlaczego otrzymuję 403 z moim kluczem tnea_? Klucze platformowe nie mogą przenosić nagłówka X-Numora-Client — usuń go.

Co się stanie, gdy mój limit się wyczerpie? Płatne wywołania zwracają 429, chyba że fallback kredytowy jest włączony na Twoim kluczu tnsr_ (albo doładujesz portfel platformowy dla kluczy tnea_).

Powiązane¶

• Rozpoczęcie pracy
• Cennik
• Rozwiązania dla firm