OAuth 2.0 dla aplikacji

OAuth 2.0 pozwala aplikacji na dostęp do Planfix w imieniu użytkownika bez żądania lub przechowywania hasła użytkownika.

Planfix używa przepływu Authorization Code z obowiązkowym PKCE S256. OAuth można wykorzystać do połączenia z REST API lub z Planfix MCP server.

Jeśli chcesz podłączyć gotowego klienta AI, zacznij od Planfix MCP. Jeśli zarządzasz dostępem w swoim koncie, zobacz Aplikacje OAuth i MCP w koncie. Partnerzy i twórcy integracji wielokontowych powinni zobaczyć Aplikacje OAuth dla partnerów.

Opcje rejestracji aplikacji

Opcja	Kiedy użyć	Gdzie działa
Aplikacja należąca do konta	Integracja jest przeznaczona dla jednego konta i klient potrzebuje z góry ustalonego client_id.	Tylko w koncie, które jest właścicielem aplikacji.
Aplikacja należąca do partnera	Ta sama aplikacja musi łączyć się z wieloma kontami klientów.	W kontach, gdzie jest to dozwolone przez politykę bezpieczeństwa lub administratora.
Automatyczna rejestracja klienta MCP	Klient MCP obsługuje Client ID Metadata Document (CIMD) lub Dynamic Client Registration (DCR).	Rejestracja sama w sobie nie przyznaje dostępu do konta. Aplikacja nadal musi zostać dozwolona w wybranym koncie.

CIMD i DCR są dostępne tylko dla połączeń MCP. Dla REST API użyj aplikacji należącej do konta lub należącej do partnera.

Punkty końcowe OAuth

Nowe integracje powinny używać globalnych punktów końcowych. Nazwa konta nie jest uwzględniona w tych adresach URL: użytkownik wybiera konto podczas autoryzacji.

Przeznaczenie	Adres
Issuer	https://auth.planfix.com
Authorization	https://auth.planfix.com/oauth/authorize
Token	https://auth.planfix.com/oauth/token
User information	https://auth.planfix.com/oauth/userinfo
Token revocation	https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration	https://auth.planfix.com/oauth/register

Metadane serwera autoryzacji są dostępne pod standardowymi punktami końcowymi:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

URI przekierowań

URI przekierowania musi być zarejestrowane w ustawieniach aplikacji. Wartość wysłana w żądaniu autoryzacji musi dokładnie odpowiadać zarejestrowanemu URI.

Dozwolone są:

• adresy https;
• adresy http tylko dla hostów loopback, takich jak localhost lub 127.0.0.1.

Port może być dynamiczny dla URI loopback, ale schemat, host, ścieżka i zapytanie muszą się zgadzać. Fragmenty URL i informacje użytkownika w URL nie są dozwolone.

Poziomy dostępu

Aplikacja otrzymuje tylko poziomy dostępu, czyli scopes, które zostały wcześniej dozwolone. Pełna lista dostępna jest w REST API access levels.

Żądany zestaw musi być podzbiorem scope'ów zarejestrowanych dla aplikacji. Scope'y aplikacji nie rozszerzają uprawnień użytkownika w Planfix: aplikacja może uzyskać dostęp tylko do danych dostępnych dla Pracownika, który ją połączył.

Aplikacje zarządzane otrzymują również zakresy serwisowe userinfo, openid i email.

Autoryzacja użytkownika

Wygeneruj code_verifier i jego reprezentację SHA-256, code_challenge, a następnie otwórz punkt końcowy autoryzacji w przeglądarce.

Przykład dla REST API:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Dla MCP dodaj parametr resource z dokładnym URL serwera MCP:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

Parametr	Opis
client_id	Identyfikator zarejestrowanej aplikacji. Dla CIMD jest to URL dokumentu metadanych klienta.
redirect_uri	Jedno z dozwolonych URI przekierowań.
response_type	Musi być code.
scope	Wymagane uprawnienia oddzielone spacjami. Ten parametr jest obowiązkowy dla REST API. Klient MCP może go pominąć, w takim przypadku używane są scope'y dozwolone dla aplikacji.
state	Losowa wartość chroniąca żądanie przed podstawieniem. Aplikacja musi ją zweryfikować po przekierowaniu.
code_challenge	Base64url bez paddingu z SHA-256 hasha code_verifier.
code_challenge_method	Wspierany jest tylko S256.
resource	Dla MCP dokładny URL https://mcp.planfix.com/mcp. Nie wysyłaj tego parametru dla REST API.

Użytkownik wybiera konto, loguje się i przegląda żądane uprawnienia. Aplikacja należąca do konta otwiera bezpośrednio konto właściciela. Jeśli polityka bezpieczeństwa wymaga zatwierdzenia przez administratora, Planfix pokaże odpowiedni krok. Administrator może zatwierdzić aplikację i połączyć ją w tej samej akcji.

Po pomyślnej autoryzacji Planfix przekierowuje przeglądarkę na redirect_uri:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Kod autoryzacyjny jest jednorazowy i jest ważny przez 10 minut.

Uzyskiwanie tokenów

Wyślij żądanie POST do /oauth/token używając application/x-www-form-urlencoded:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

Dla MCP powtórz parametr resource z tą samą wartością, która została użyta w żądaniu autoryzacji.

Klient publiczny wysyła żądanie bez sekretu. Klient poufny dodatkowo uwierzytelnia się używając client_secret_basic lub parametrów client_id i client_secret w ciele żądania.

Przykładowa odpowiedź:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Dla REST API odpowiedź zawiera również account_name, account_domain i account_url. Zapisz te wartości i używaj URL wybranego konta do żądań REST API.

Token dostępu jest ważny przez 24 godziny. Jest powiązany z użytkownikiem, kontem, aplikacją, scope'ami i resource. Token wydany dla MCP nie może być użyty bezpośrednio z REST API, a token REST API nie może być użyty z MCP.

Użycie tokena z REST API

Prześlij token w nagłówku Authorization:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Używaj URL konta zwróconego podczas wymiany kodu autoryzacyjnego na tokeny. Dostępne są tylko metody objęte przyznanymi scope'ami. Tokeny OAuth podlegają planowi konta i standardowym REST API limits.

Informacje o użytkowniku

Żądanie userinfo wymaga scope'u openid:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Przykładowa odpowiedź gdy obecny jest scope email:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Globalna autoryzacja OAuth jest dostępna dla Pracowników konta. Planfix nie wydaje id_token; pobieraj dane użytkownika przez userinfo.

Odświeżanie tokenów

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

Dla MCP wyślij ponownie ten sam resource. Klient poufny musi się uwierzytelnić używając swojego sekretu.

Planfix zwraca nowy token dostępu i nowy refresh token. Poprzedni refresh token staje się natychmiast nieważny, więc aplikacja musi atomowo zastąpić przechowywaną wartość.

Unieważnianie tokena

Klient może unieważnić refresh token przez /oauth/revoke:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Użytkownik może również usunąć połączenie w sekcji Session management w karcie użytkownika. Administrator może unieważnić zgodę aplikacji zewnętrznej dla całego konta. Zobacz Aplikacje OAuth i MCP w koncie.

Zgodność z istniejącymi integracjami

Punkty końcowe tenantów takie jak https://account.planfix.com/api/v2/oauth/authorize, /token i /userinfo nadal działają dla istniejących integracji powiązanych z konkretnym kontem.

Do nowych integracji używaj globalnych punktów końcowych. Obsługują one standardowe odkrywanie metadanych, wybór konta i MCP. Nie mieszaj globalnych i tenantowych punktów końcowych w jednej sesji OAuth.

Zalecenia dotyczące bezpieczeństwa

• Zawsze używaj PKCE S256 i waliduj state.
• Używaj klienta publicznego bez sekretu dla aplikacji mobilnych, desktopowych i działających w przeglądarce.
• Używaj klienta poufnego tylko wtedy, gdy sekret może być przechowywany bezpiecznie na serwerze.
• Żądaj minimalnego niezbędnego zestawu scope'ów.
• Nie zapisuj tokenów dostępu, tokenów odświeżających, kodów autoryzacyjnych, code_verifier ani sekretów klienta do logów.
• Przechowuj refresh tokeny i sekrety klienta w zaszyfrowanym magazynie.
• Waliduj iss w odpowiedzi i akceptuj tylko oczekiwany issuer Planfix.

Możliwe błędy

Błąd	Przyczyna
invalid_client	Klient jest nieznany lub wyłączony, sekret klienta jest nieprawidłowy lub aplikacja nie jest dostępna w wybranym koncie.
invalid_grant	Kod autoryzacyjny lub refresh token jest nieprawidłowy, wygasł, został już użyty lub nie pasuje do klienta, redirect URI, danych PKCE lub resource.
invalid_scope	Żądanie zawiera scope, który nie jest dozwolony dla aplikacji.
invalid_target	resource jest nieobsługiwany lub zmienił się między żądaniami.
access_denied	Użytkownik odrzucił połączenie lub polityka konta nie pozwala aplikacji.
HTTP 401, invalid_token	Token dostępu jest nieznany, wygasł lub został unieważniony.
HTTP 403, insufficient_scope	Token nie zawiera scope'u wymaganego dla operacji.

Przejdź do

• Planfix MCP
• Aplikacje OAuth i MCP w koncie
• Aplikacje OAuth dla partnerów
• REST API
• REST API Authorization
• REST API: Access Levels List – scope