Przejdź do głównej treści
Pozwól użytkownikom autoryzować Twoją aplikację do uzyskiwania dostępu do ich profilu Ace Data Cloud, subskrypcji usług, API Key, użycia lub zamówień. Użyj standardowego Authorization Code + S256 PKCE: aplikacja otwiera stronę autoryzacji, a po wyrażeniu zgody przez użytkownika otrzymuje jednorazowy code, który następnie wymienia na OAuth access token. OAuth access token służy do uzyskiwania dostępu do interfejsów zasobów konta; do wywoływania model API użyj odpowiedniego API Key. Autoryzacja OAuth nie tworzy automatycznie API Key, nie aktywuje usług ani nie zwiększa salda.

Wybór sposobu integracji

Standardowe przekierowanie nie wymaga embed=studio, embed_origin ani postMessage. W trybie komponentu Studio host tworzy stronę autoryzacji i utrzymuje most komunikatów; strony trzecie integrują się zgodnie z protokołem komponentu na końcu tego dokumentu i nie powinny samodzielnie konstruować tych dwóch parametrów.

Endpointy i dokument wykrywania

Interfejs zarządzania aplikacjami wymaga uwierzytelnienia zalogowanego konta i nie jest interfejsem anonimowej dynamicznej rejestracji (DCR). Własne adresy wykrywania/rejestracji usługi MCP oraz endpointy OAuth konta w tej tabeli są różnymi wejściami; podczas łączenia z konkretnym MCP postępuj zgodnie z dokumentacją i wynikami wykrywania tej usługi. Dokument wykrywania służy do uzyskiwania endpointów i możliwości protokołu. Bieżący proces zwraca OAuth token, a nie id_token; nie obsługuj go jako pełnego procesu logowania OpenID Connect wyłącznie dlatego, że istnieje scope openid.

Zakresy uprawnień: używaj bieżących nazw scope

scope to rozdzielone spacjami, rozróżniające wielkość liter nazwy uprawnień. Nowe aplikacje używają konkretnych uprawnień, takich jak profile:read, email:read, phone:read.

Skąd uzyskać dostępne do żądania uprawnienia

Po zalogowaniu interfejs listy aplikacji OAuth GET /api/v1/oauth2/applications/ zwraca available_scopes; selektor uprawnień na stronie zarządzania aplikacją używa tego samego katalogu. Są to opcjonalne zakresy, których powinny używać zwykłe aplikacje samoobsługowe. scopes_supported w Discovery zawiera wszystkie nazwy uprawnień rozpoznawane przez platformę, nie oznacza to, że Twoja aplikacja może żądać każdej z nich. Rzeczywista autoryzacja sprawdza jednocześnie:
  1. czy uprawnienie może być delegowane do tego typu aplikacji;
  2. czy uprawnienie zostało zarejestrowane w dozwolonych zakresach tej aplikacji OAuth;
  3. czy bieżący użytkownik posiada żądane uprawnienie.
Nieznane, niezarejestrowane, niedozwolone do delegowania lub nieposiadane przez użytkownika uprawnienia zwracają invalid_scope. Podczas wymiany kodu autoryzacyjnego i odświeżania są one również ponownie sprawdzane; uprawnienia nie są automatycznie uzupełniane ani podnoszone.

Opcjonalne uprawnienia dla zwykłych aplikacji samoobsługowych

Poniżej znajduje się bieżący katalog (2026-10-09); podczas integracji kieruj się available_scopes. Na przykład do samego odczytu profilu użyj profile:read; jeśli potrzebny jest również e-mail, dodaj email:read; aby odczytać istniejące API Key, użyj profile:read credentials:read. O credentials:write proś tylko wtedy, gdy rzeczywiście musisz tworzyć lub modyfikować Key, a jeśli potrzebujesz odświeżania, dodaj offline_access. Niektóre uprawnienia są przeznaczone wyłącznie dla zaufanych aplikacji zatwierdzonych przez platformę, na przykład sites:read, sites:write, platform-tokens:read; inne uprawnienia nie są otwarte dla zwykłych aplikacji OAuth stron trzecich. Typ klienta public/confidential opisuje, czy może on bezpiecznie przechowywać secret, i nie ma związku z tym, czy aplikacja jest zaufana. Aplikacje tworzone samoobsługowo nie mogą samodzielnie włączać zaufanych uprawnień. account to selektor uprawnień konta używany przez wskazany oficjalny MCP zarządzania kontem, a nie scope „wszystkie uprawnienia” dla aplikacji stron trzecich i nie może być mieszany z innymi scope. Strony trzecie powinny wyraźnie wymieniać wymagane konkretne uprawnienia.

Migracja ze starej dokumentacji

Stare nazwy nie są akceptowane jako kompatybilne aliasy. Równocześnie zaktualizuj scopes zarejestrowane dla aplikacji OAuth, adres URL autoryzacji i własną kontrolę uprawnień; zmiana konfiguracji aplikacji nie doda uprawnień do już wydanych tokenów, użytkownik musi ponownie dokonać autoryzacji.

Krok 1: zarejestruj aplikację OAuth

Otwórz zarządzanie aplikacjami OAuth, utwórz aplikację i wypełnij:
  • Nazwa, opis, logo aplikacji: wyświetlane po stronie aplikacji na stronie autoryzacji.
  • Typ klienta: dla czysto frontendowych, mobilnych lub desktopowych klientów wybierz Public; dla usług, które mogą przechowywać secret na backendzie, wybierz Confidential.
  • Adres zwrotny: w środowisku produkcyjnym używaj HTTPS i zarejestruj pełny URL, pod którym aplikacja faktycznie obsługuje callback.
  • Uprawnienia: wybierz faktycznie potrzebne scopes z katalogu dostępnego na stronie.
Zapisz client_id. Klient Confidential przechowuje client_secret po stronie serwera; nie może on trafić do HTML, zmiennych budowania frontendu ani URL. Klient Public nie używa secret podczas wymiany tokenu; nawet jeśli odpowiedź rejestracji zawiera to pole, nie należy traktować go jako poświadczenia, które klient może zachować w tajemnicy. redirect_uri musi być dokładnie taki sam podczas rejestracji, autoryzacji i wymiany tokenu, w tym ścieżka, końcowy ukośnik i parametry zapytania. Każde konto może utworzyć maksymalnie 20 aplikacji. Secret jest wyświetlany tylko podczas tworzenia/rotacji; po rotacji stary secret nie może być dalej używany do wymian wymagających uwierzytelnienia klienta.

Krok 2: przycisk inicjuje autoryzację

Przy każdym kliknięciu połączenia wygeneruj nowe losowe state i code_verifier, oblicz:
Zapisz state, verifier i adres zwrotny w własnej sesji aplikacji, a następnie otwórz stronę autoryzacji z parametrami zakodowanymi w URL:
Klient Public musi wysyłać PKCE S256. Chociaż Discovery nadal wymienia plain, klient Public nie może go używać. Klientowi Confidential również zaleca się używanie S256; jeśli podczas inicjowania autoryzacji użyto PKCE, podczas wymiany należy przesłać odpowiadający verifier. Po wyrażeniu zgody przez użytkownika następuje powrót do redirect_uri, a parametry zapytania zawierają code i zwrócony bez zmian state. W przypadku odmowy zwracane są error=access_denied, opis błędu oraz state. Przed obsługą callbacku najpierw zweryfikuj, że state pasuje do bieżącej sesji. Kod autoryzacyjny jest ważny przez 10 minut i można go wymienić tylko raz; po niepowodzeniu należy ponownie zainicjować połączenie, zamiast wielokrotnie odświeżać stary URL callbacku.

Krok 3: wymiana na token OAuth

Klient Public wymienia token bezpośrednio z przeglądarki lub klienta; klient Confidential wymienia go na własnym backendzie. Treść żądania obsługuje kodowanie formularza, a poniższe zmienne reprezentują dane uzyskane przez aplikację w tej autoryzacji:
Klient Confidential musi dodatkowo dodać po stronie serwera pole formularza client_secret. Obecnie obsługiwane jest client_secret_post; nie traktuj uwierzytelnienia klienta HTTP Basic jako obsługiwanej metody. Z udanej odpowiedzi odczytaj access_token, token_type, expires_in oraz faktycznie przyznany scope. refresh_token jest dostępny tylko, jeśli zażądano i przyznano offline_access. Nie traktuj OAuth access token jako API Key API modelu i nie zapisuj tokenu, verifiera ani kodu autoryzacyjnego w logach, zdarzeniach analitycznych ani linkach udostępniania.

Krok 4: odczyt informacji o użytkowniku i API Key

Najpierw użyj OAuth access token do wysłania żądania UserInfo:
Zwracane pola zależą od scope: id jest identyfikatorem użytkownika; profile:read lub openid umożliwia odczyt podstawowych danych (takich jak username, nickname, avatar, is_verified, date_joined, registration_method); e-mail wymaga email:read, a numer telefonu i region wymagają phone:read. Nie zakładaj, że nieautoryzowane pola zawsze istnieją. Gdy potrzebny jest istniejący API Key i przyznano credentials:read, użyj id z UserInfo jako warunku filtrowania:
Zwracana lista używa count i items, a pole Key to items[*].token, nie data[0].value. user_id=me nie jest prawidłowym ID użytkownika dla tego interfejsu. Dane z wielu stron odczytuj dalej za pomocą offset/limit; nie traktuj pierwszej strony jako wszystkich poświadczeń. Wybieraj odpowiednie poświadczenia według aplikacji, usługi i statusu ważności; nie pobieraj bezrefleksyjnie pierwszego wpisu. Pusta lista nie oznacza niepowodzenia autoryzacji; użytkownik mógł jeszcze nie utworzyć odpowiedniego Key. Kontrola uprawnień OAuth access token oraz zakres usługi, limity i warunki wygaśnięcia samego API Key są odrębnymi ograniczeniami. Zezwolenie na odczyt API Key oznacza, że strona trzecia może go zapisać i używać. Cofnięcie żądania OAuth lub wyczyszczenie stanu logowania aplikacji nie unieważni już skopiowanego API Key; użytkownik musi osobno cofnąć lub zrotować ten Key w zarządzaniu poświadczeniami.

Działający przykład przeglądarkowy Public / PKCE

Wdróż poniższą stronę pod zarejestrowanym REDIRECT_URI, zastąp CLIENT_ID i adres callbacku. Przycisk inicjuje standardową autoryzację, a po powrocie na tę samą stronę odczytuje dane profilu i liczbę istniejących Key. Przykład nie wyświetla ani nie utrwala Key; aplikacja produkcyjna wykorzystuje wyniki zgodnie z rzeczywistym zastosowaniem. Najpierw zweryfikuj na niezależnej stronie przeglądarki, a następnie przeprowadź odbiór zgodnie z późniejszymi wymaganiami dotyczącymi iframe.
Przykładowe wywołanie zwrotne i punkt wejścia muszą znajdować się pod tym samym originem, w tej samej karcie przeglądarki / iframe, aby można było odczytać wcześniej zapisany sessionStorage. Aplikacja produkcyjna powinna zarządzać tokenami we własnym mechanizmie sesji, obsługiwać ich wygaśnięcie oraz usuwać parametry URL autoryzacji po otrzymaniu odpowiedzi; główny interfejs strony powinien zostać wyrenderowany najpierw, a awarie sieci powinny wpływać wyłącznie na stan połączenia.

iframe na stronie white-label

Strona klienta samodzielnie przekierowuje na stronę autoryzacji

Wystarczy użyć standardowych parametrów OAuth i własnej obsługi wywołania zwrotnego; window.location.assign() nawiguje bieżący iframe, a strona nadrzędna pozostaje w domenie white-label. Nie ma potrzeby dodawania embed=studio dla ikon ani implementowania protokołu wiadomości Studio. Należy spełnić następujące warunki:
  • Strona aplikacji i strona wywołania zwrotnego używają HTTPS, są faktycznie dostępne i zezwalają na osadzenie przez iframe z domeny nadrzędnej white-label; sprawdź Content-Security-Policy: frame-ancestors i X-Frame-Options po obu stronach.
  • Sandbox zezwala na wymagane przez stronę skrypty, formularze oraz możliwości originu / przechowywania danych. Przy obsłudze logowania w wyskakującym oknie wymagane są również odpowiednie możliwości wyskakujących okien; preferuj konfigurację komponentu Website udostępnianą przez Studio.
  • Przeglądarka zezwala na używanie w bieżącym scenariuszu osadzenia pamięci wymaganej przez stan autoryzacji. Stan logowania do strony white-label i stan logowania AuthFrontend mogą się różnić; nie należy zakładać, że zalogowanie do strony white-label oznacza już zalogowanie na stronie autoryzacji.
  • Usługa wymiany tokenów w wywołaniu zwrotnym jest dostępna, a żądania międzyoriginowe zezwalają na origin aplikacji; błędy DNS, CORS i HTTP muszą wyświetlać stan umożliwiający ponowienie próby i nie mogą powodować zatrzymania renderowania całej strony.
Lewa strona strony autoryzacji odczytuje Logo aplikacji OAuth; prawa strona odczytuje favicon / logo tej Site, gdy przeglądarka może przekazać origin nadrzędny, a domena nadrzędna przejdzie weryfikację zweryfikowanej strony, w przeciwnym razie wyświetlana jest domyślna ikona. Decyduje to wyłącznie o prezentacji marki, nie ustanawia sesji logowania ani nie udostępnia stronie klienta uprawnień do konta. Bieżące ograniczenie: gdy zwykły OAuth w iframe wymaga ponownego logowania, nadal występuje luka w procesie powrotu do strony autoryzacji po ukończeniu logowania. Przed wdrożeniem należy osobno przeprowadzić odbiór dla „Auth zalogowany” oraz „Auth niezalogowany / wygasły”. Dopóki ta luka nie zostanie naprawiona i zweryfikowana, pierwsze logowanie może używać osobnej strony do ukończenia standardowego OAuth albo autoryzacji komponentu Studio opisanej poniżej; nie należy obiecywać działania we wszystkich scenariuszach iframe wyłącznie na podstawie wyników testów w stanie zalogowania.

Używanie do autoryzacji bieżącego konta Studio

W Studio włącz OAuth w „Ustawienia → Strona główna → Komponenty strony”, wpisz client_id i zarejestrowany adres wywołania zwrotnego. Strona i wywołanie zwrotne muszą używać tego samego originu HTTPS oraz różnić się od originu Studio. Strona trzecia musi:
  1. Wysłać acedatacloud:oauth:ready do dokładnego originu strony nadrzędnej, odebrać i zweryfikować acedatacloud:oauth:init.
  2. Przycisk generuje state i verifier PKCE, wysyła acedatacloud:oauth:authorize (state, wyzwanie S256); verifier pozostaje wewnątrz własnej strony.
  3. Zweryfikować okno nadrzędne, origin i state, obsłużyć code lub error w acedatacloud:oauth:result oraz wymienić je zgodnie ze standardowym punktem końcowym tokenów. Studio wyświetla stronę autoryzacji w obszarze komponentu, po zgodzie użytkownika zwraca kod autoryzacyjny w wiadomości, aplikacja nie musi przekierowywać. Gdy nie ma logowania, zwracane jest login_required, przy odmowie zwracane jest access_denied, a po przekroczeniu czasu oczekiwania zwracane jest authorization_timeout. Zmiana konta przebuduje iframe aplikacji i anuluje nieukończoną autoryzację.
Komponent obecnie żąda profile:read credentials:read, nie obejmuje offline_access. Nie zakładaj, że zawsze można otrzymać refresh token. embed=studio i embed_origin są utrzymywane przez hosta Studio oraz stronę autoryzacji, strona klienta musi jedynie przestrzegać protokołu wiadomości. Pełny przykład przycisku znajduje się w Przewodniku integracji OAuth komponentów witryny Studio.

Cykl życia, odświeżanie i unieważnianie

Domyślny okres ważności access tokena wynosi 15 dni, odświeżanie lub ponowną autoryzację należy zaplanować na podstawie expires_in z każdej odpowiedzi; refresh token domyślnie jest ważny 30 dni, a jego okres zależy od konfiguracji usługi. Nie koduj tych dwóch wartości na stałe jako wieczystych gwarancji. Po przyznaniu offline_access można wywołać:
Odświeżenie zwróci nowe tokeny, aplikacja powinna zapisać najnowsze wartości. Podczas odświeżania sprawdzane jest, czy aplikacja jest nadal ważna, użytkownik jest dostępny i uprawnienia są nadal przyznane. W przypadku niepowodzenia wyczyść własny stan połączenia i przeprowadź ponowną autoryzację. Obecna implementacja odświeżania OAuth nie gwarantuje natychmiastowego unieważnienia starego refresh tokena po odświeżeniu. Nie traktuj otrzymania nowego tokena jako oznaki, że stary token został unieważniony, ani nie zastępuj zakończenia istniejących tokenów rotacją secretu. Sposób wywołania żądania unieważnienia to:
Obecny endpoint unieważniania zwraca HTTP 200, ale nie implementuje natychmiastowego unieważniania wydanych JWT. Aplikacja powinna wyczyścić zapisane przez siebie tokeny i nie może traktować 200 jako dowodu, że wszystkie wydane tokeny lub API Key zostały unieważnione. W przypadku ujawnionych lub skopiowanych API Key należy oddzielnie unieważnić lub obrócić odpowiednie poświadczenia.

Typowe błędy i odbiór

Przed dostarczeniem zweryfikuj co najmniej: poprawny callback, odmowę, błędny state, wygasły/wykorzystany code, brak Key, awarię sieci, wygaśnięcie tokena, brak wymaganego scope, a także pierwsze logowanie i zmianę konta w scenariuszu iframe. W dowodach testowych nie zapisuj pełnego code, tokena ani API Key.

Weryfikacja dwuetapowa i ponowna autoryzacja

Po włączeniu przez użytkownika weryfikacji dwuetapowej Ace Data Cloud przeprowadzi na stronie autoryzacji weryfikację kodu z aplikacji uwierzytelniającej lub jednorazowego kodu odzyskiwania, a następnie dostarczy kod autoryzacyjny. Twoja aplikacja nadal używa standardowego przepływu OAuth i nie powinna żądać od użytkownika, zapisywać ani przekazywać kluczy aplikacji uwierzytelniającej ani kodów odzyskiwania. Po włączeniu, zmianie, wyłączeniu weryfikacji dwuetapowej przez użytkownika lub odzyskaniu konta poprzednie sesje konta, tokeny odświeżania i powiązane tokeny autoryzacji platformy mogą utracić ważność. Po otrzymaniu nieprawidłowej sesji lub invalid_grant ponownie uruchom widoczny dla użytkownika proces autoryzacji, nie używaj wielokrotnie starego kodu autoryzacyjnego ani nie próbuj omijać weryfikacji. Sposób uwierzytelniania zwykłych API Key modeli pozostaje bez zmian; jeśli istnieje podejrzenie przejęcia konta, należy oddzielnie sprawdzić i unieważnić dotknięte API Key.