Aplikacje OAuth dla partnerów

Z Planfix

Aplikacja OAuth należąca do partnera przeznaczona jest dla integracji, która łączy się z wieloma kontami Planfix. Te same dane uwierzytelniające aplikacji są używane dla wszystkich kont klientów, podczas gdy każde konto kontroluje dostęp oddzielnie, a każdy użytkownik wyraża zgodę na własne połączenie.

Jeżeli integracja jest przeznaczona tylko dla jednego konta, łatwiej jest utworzyć account-owned application.

Tworzenie aplikacji

  1. Otwórz swoje konto partnerskie.
  2. Przejdź do OAuth applications.
  3. Wybierz Create application.
  4. Wprowadź nazwę i opis, które zobaczą użytkownicy i administratorzy.
  5. Wybierz typ klienta OAuth.
  6. Dodaj redirect URI.
  7. Wybierz minimalne wymagane zakresy REST API.
  8. Zapisz aplikację i skopiuj jej dane uwierzytelniające.

Nowa aplikacja jest prywatna i wymaga wyraźnej akceptacji na każdym koncie, do którego się łączy.

Typ klienta OAuth

Typ Przeznaczenie aplikacji Dane uwierzytelniające
Public Aplikacje mobilne, desktopowe i przeglądarkowe oraz lokalni klienci MCP. Tylko client_id. Nie ma client_secret; obowiązkowe PKCE S256.
Confidential Aplikacje po stronie serwera, gdzie secret może być przechowywany poza urządzeniem użytkownika oraz kod po stronie klienta. client_id i client_secret.

Typ klienta OAuth jest niezależny od publikacji aplikacji. Na przykład prywatna aplikacja mobilna jest publicznym klientem OAuth bez secreta.

Redirect URI

Określ każdy adres URL, na który Planfix może przekierować użytkownika po logowaniu.

  • Używaj https dla serwisu webowego.
  • http jest dozwolone tylko dla adresów loopback, takich jak localhost i 127.0.0.1.
  • Klient może używać dynamicznego portu dla adresu loopback, ale schemat, host, ścieżka i query muszą się zgadzać.
  • Nie używaj wildcardów, fragmentów URL ani redirect URI, którymi nie zarządzasz.

Zakresy (scopes)

Zakresy definiują maksymalne uprawnienia aplikacji. Żądaj tylko poziomów dostępu wymaganych z REST API scope list.

Zakresy aplikacji nie zastępują normalnych uprawnień użytkownika. Nawet gdy zakres jest przyznany, aplikacja może pracować tylko z danymi dostępnymi dla danego użytkownika.

Zmiana redirect URI lub zakresów tworzy nową wersję do zatwierdzenia. Wcześniej połączone konta muszą przejrzeć i zatwierdzić nową wersję, a użytkownicy muszą ponownie połączyć się.

Łączenie konta klienta

Prywatna aplikacja należąca do partnera musi być wyraźnie zatwierdzona przez administratora na każdym koncie.

  1. Otwórz aplikację na swoim koncie partnerskim.
  2. W obszarze linku zatwierdzającego wpisz nazwę konta klienta.
  3. Skopiuj wygenerowany link i prześlij go administratorowi tego konta.
  4. Poproś administratora, aby zweryfikował właściciela, redirect URI i zakresy, a następnie zatwierdził aplikację.
  5. Po zatwierdzeniu, użytkownicy na koncie mogą dokończyć autoryzację OAuth. Każdy użytkownik wyraża zgodę oddzielnie we własnym imieniu.

Link otwiera Account management → API → OAuth and MCP applications i wyświetla żądaną aplikację.

Administrator, który jednocześnie łączy aplikację, może wybrać Approve and connect.

Aplikacje prywatne i publikowane

Status Jak jest dopuszczana na konto
Private Zawsze wymaga wyraźnej akceptacji administratora każdego konta.
Published Dostępna bez oddzielnej akceptacji, gdy polityka konta to Allow published applications. Nadal wymaga zatwierdzenia, gdy polityka to Approved applications only.

Publikacja to odrębny proces przeglądu w Planfix. Przed złożeniem aplikacji do publikacji przygotuj klarowną nazwę i opis, minimalny zestaw zakresów, działające redirect URI i dokumentację dla użytkowników dotyczącą łączenia i usuwania integracji. Skontaktuj się z Planfix Support w sprawie procedury publikacji.

Adresy połączeń

Używaj globalnych endpointów OAuth:

Przeznaczenie Adres
Authorization https://auth.planfix.com/oauth/authorize
Token https://auth.planfix.com/oauth/token
Userinfo https://auth.planfix.com/oauth/userinfo
MCP https://mcp.planfix.com/mcp

Nie dodawaj nazwy konta do globalnego URL. Użytkownik wybiera konto na stronie Planfix. Pełny protokół, łącznie z resource, PKCE, odświeżaniem tokenów i unieważnianiem, jest opisany w OAuth 2.0 dla aplikacji.

Zarządzanie aplikacją

Partner może:

  • edytować nazwę i opis;
  • zmieniać redirect URI i zakresy;
  • wyłączać i ponownie włączać aplikację;
  • rotować client secret w aplikacji typu confidential;
  • generować link zatwierdzający aplikację dla konkretnego konta.

Po rotacji secreta, stary client secret przestaje działać natychmiast. Zaktualizuj secret na serwerze integracji i nigdy nie wysyłaj go użytkownikom.

Wyłączenie aplikacji blokuje autoryzację OAuth i wydane tokeny na wszystkich kontach. Ta akcja wpływa na wszystkich klientów korzystających z aplikacji.

Zalecenia przed uruchomieniem

  • Używaj Authorization Code z PKCE S256 i waliduj state.
  • Żądaj tylko potrzebnych zakresów.
  • Po zalogowaniu pokaż użytkownikowi wybrane konto.
  • Obsługuj rotację refresh tokenów: po pomyślnym odświeżeniu poprzedni refresh token przestaje być ważny.
  • Nie zapisuj tokenów, kodów autoryzacyjnych, code_verifier ani client secretów do logów.
  • Udokumentuj, jak użytkownicy mogą rozłączyć integrację i zażądać usunięcia swoich danych.
  • Przetestuj scenariusze wycofania zatwierdzenia, wyłączenia aplikacji i ponownego łączenia.

Przejdź do