Tokeny
Tokeny to poświadczenia używane do autoryzacji żądań do interfejsu API Altium 365. Wszystkie żądania API muszą zawierać prawidłowy token w nagłówku Authorization.
Tokeny są tworzone w Twoim Workspace w sekcji Admin → Developer. Tylko administratorzy Workspace mogą tworzyć tokeny.
Typy tokenów
Dostępne są dwa typy tokenów, różniące się sposobem użycia oraz kompromisami w zakresie bezpieczeństwa.
Długoterminowy token dostępu
Pojedyncze poświadczenie używane bezpośrednio jako token bearer w żądaniach API. Jego okres ważności konfigurujesz podczas tworzenia – maksymalnie do 1 roku.
Authorization: Bearer {token}
To prostsza opcja: jedna wartość używana bezpośrednio. Dobrze sprawdza się w skryptach, automatyzacji i lokalnym środowisku programistycznym, gdzie łatwość użycia jest ważniejsza niż rotacja poświadczeń.
Główne ograniczenie polega na tym, że wartość tokenu nie zmienia się przez cały okres jego ważności. Jeśli zostanie ujawniona, pozostaje ważna aż do wygaśnięcia lub ręcznego unieważnienia.
Refresh Token
Bardziej bezpieczna opcja, która oddziela długoterminowe poświadczenie od krótkoterminowego używanego w żądaniach API. Przy tworzeniu otrzymujesz trzy wartości:
-
Client ID – identyfikuje klienta tokenu
-
Client secret – uwierzytelnia klienta tokenu
-
Refresh token – długoterminowe poświadczenie
Wymieniasz je na krótkoterminowy access token, wywołując punkt końcowy tokenu. Token dostępu jest tym, którego używasz w żądaniach API. Gdy wygaśnie, żądasz nowego, używając tego samego refresh tokenu.
Refresh token ma konfigurowalny okres ważności do 1 roku. Generowane przez niego tokeny dostępu są krótkoterminowe.
To podejście lepiej nadaje się do integracji produkcyjnych:
-
Poświadczenie przesyłane z każdym żądaniem API (token dostępu) jest krótkoterminowe
-
Długoterminowy sekret (refresh token) pozostaje w Twoim bezpiecznym magazynie i nigdy nie jest wysyłany bezpośrednio do API
Zobacz Using a Refresh Token , aby poznać przebieg wymiany tokenu.
Wybór typu tokenu
|
Długoterminowy token dostępu |
Refresh Token |
Liczba poświadczeń |
1 (token dostępu) |
3 (client ID + client secret + refresh token) |
Poświadczenie używane w żądaniu API |
Sam token |
Krótkoterminowy token dostępu (przez wymianę) |
Rotacja |
Ręczna |
Automatyczna poprzez wymianę |
Najlepsze zastosowanie |
Skrypty, lokalny development, testowanie |
Integracje produkcyjne |
Zakresy
Każdy token jest powiązany z zestawem OAuth scopes, które określają, jakie operacje API może autoryzować. Zakresy są konfigurowane podczas tworzenia tokenu i nie można ich później zmienić.
Zobacz OAuth Scopes, aby uzyskać pełną listę dostępnych zakresów i informacje o tym, jak mapują się na możliwości API.
Okres ważności tokenu
Oba typy tokenów mają konfigurowalny okres ważności do 1 roku, ustawiany w momencie tworzenia. Nie ma automatycznego odnawiania — po wygaśnięciu tokenu trzeba utworzyć nowy.
W przypadku refresh tokenów okres ważności dotyczy samego refresh tokenu. Generowane przez niego tokeny dostępu mają krótszy, stały okres ważności wynoszący 1 godzinę.
Unieważnianie tokenu
Tokeny można unieważnić w sekcji Admin → Developer w dowolnym momencie. Unieważnienie tokenu powoduje jego natychmiastowe wyłączenie — wszelkie żądania API używające tego tokenu zakończą się błędem autoryzacji.
Tłumaczenie SI