Autoryzacja

Każdy request do naszych systemów musi zostać poprawnie autoryzowany.

Autoryzacja odbywa się za pomocą OAuth 2.0.

OAuth 2.0 to system, który pozwala aplikacjom na bezpieczny dostęp do czynności na naszym serwerze, bez konieczności udostępniania haseł. Twój system loguje się za pomocą klucza (token dostępu).

Wygeneruj token dostępu

Aby uzyskać token dostępu, wyślij żądanie POST z typem zawartości application/x-www-form-urlencoded na endpoint:

https://api.tpay.com/oauth/auth

Sprawdź szczegóły w dokumentacji API Reference: POST /oauth/auth

W zapytaniu określ następujące parametry:

client_id	Identyfikator klienta.
client_secret	Hasło klienta.

Parametry te możesz wygenerować w Panelu Akceptanta.

Przejdź do Panelu Akceptanta i wybierz Integracja > API.
W sekcji Klucze do Open API, kliknij w Dodaj nowy klucz.
Zaznacz i skopiuj wygenerowany klucz i hasło, następnie zapisz je w bezpiecznym miejscu - hasło do nowo powstałego klucza jest widoczne tylko przy pierwszym wygenerowaniu.

Przechowuj bezpiecznie dane autoryzacyjne

Bezpieczne przechowywanie klucza dostępu (tokenu) jest kluczowe dla ochrony Twoich systemów oraz płatności. Oto kilka zasad, które warto przestrzegać:

Unikaj przechowywania w kodzie:

Nigdy nie zapisuj kluczy bezpośrednio w kodzie aplikacji, zwłaszcza w plikach, które mogą być publicznie dostępne (np. repozytoria kodu).

Użyj zmiennych środowiskowych:

Przechowuj klucze w zmiennych środowiskowych, które mogą być odczytane przez aplikację w czasie wykonywania, ale nie są przechowywane w kodzie źródłowym.

Zaszyfruj klucze:

Przechowuj klucze w zaszyfrowanej formie.

Ogranicz dostęp:

Upewnij się, że tylko uprawnione osoby i usługi mają dostęp do kluczy. Skonfiguruj odpowiednie polityki dostępu (IAM policies) w swojej infrastrukturze.

Regularnie rotuj klucze:

Zmieniaj klucz regularnie, aby minimalizować ryzyko ich wycieku. Upewnij się, że proces rotacji nie zakłóca działania aplikacji.

Monitoruj użycie:

Monitoruj użycie kluczy dostępu, aby wykrywać i reagować na podejrzane aktywności.

Używaj bezpiecznych bibliotek i narzędzi:

Korzystaj z uznanych bibliotek i narzędzi do zarządzania kluczami i ich przechowywania, które są regularnie aktualizowane i sprawdzane pod kątem bezpieczeństwa.

Wyślij zapytanie o token OAuth

Aby utworzyć token autoryzacyjny, wyślij żądanie POST na endpoint:

https://api.tpay.com/oauth/auth

Sprawdź szczegóły w dokumentacji API Reference: POST /oauth/auth

W zapytaniu określ następujące parametry:

client_id	Identyfikator klienta.
client_secret	Hasło klienta.

Przykład:

curl -X POST https://api.tpay.com/oauth/auth -d 'client_id=testclient&client_secret=testpass'

Przykład odpowiedzi:

{
  "issued_at": 1718215429,
  "scope": "read",
  "token_type": "Bearer",
  "expires_in": 7200,
  "client_id": "01HH1N1V033B5FMB6TXPWZVATY-01J06SX1HPPFG0D8907TWBG871",
  "access_token": "3a06d08eb804f8bb4a8b2c82bf14c15cbae79ef6"
}

Parametry odpowiedzi:

issued_at	Znacznik czasu (w formacie Unix timestamp) wskazujący moment, w którym token został wygenerowany. Wartość ta reprezentuje liczbę sekund od 1 stycznia 1970 roku (UTC).
scope	Zakres uprawnień przyznanych tokenowi. W tym przypadku token umożliwia odczyt danych (read).
token_type	Typ tokena używanego do autoryzacji. Token typu Bearer oznacza, że aplikacja może uzyskać dostęp do zasobów poprzez przekazanie tego tokena w nagłówku HTTP Authorization.
expires_in	Czas ważności tokena w sekundach. W tym przypadku token wygaśnie po 7200 sekundach (2 godzinach) od momentu jego wygenerowania.
access_token	Token dostępu używany do autoryzacji. Ten token musi być przesyłany w nagłówku HTTP Authorization w formacie: Bearer <access_token>.

Uwaga

Access token należy przechować w aplikacji i używać go do autoryzacji żądań aż do momentu jego wygaśnięcia.
Token jest ważny przez okres podany w parametrze expires_in (domyślnie 2 godziny).
Po wygaśnięciu tokena aplikacja powinna pobrać nowy token. Ważne jest, aby nie próbować pobierać nowego tokena przy każdym żądaniu, lecz polegać na już wygenerowanym tokenie do momentu jego wygaśnięcia.
Czas ważności tokena może się zmieniać, dlatego należy odpowiednio zarządzać jego przechowywaniem i odnawianiem.