OAuth aplikace pro partnery

Aplikace vlastněná partnerem je určena pro integraci, která se připojuje k více účtům Planfixu. Pro všechny zákaznické účty se používají stejné přihlašovací údaje aplikace, přičemž každý účet řídí povolení samostatně a každý uživatel souhlasí s vlastním připojením.

Pokud je integrace určena pouze pro jeden účet, je jednodušší vytvořit account-owned application.

Vytvoření aplikace

Otevřete svůj partnerský účet.
Přejděte na OAuth applications.
Vyberte Create application.
Zadejte název a popis, které uvidí uživatelé a administrátoři.
Vyberte typ OAuth klienta.
Přidejte redirect URI.
Vyberte minimální požadované REST API scopes.
Uložte aplikaci a zkopírujte její přihlašovací údaje.

Nová aplikace je soukromá a vyžaduje explicitní schválení v každém účtu, ke kterému se připojuje.

Typ OAuth klienta

Typ	Určené aplikace	Přihlašovací údaje
Public	Mobilní, desktopové a prohlížečové aplikace a lokální MCP klienti.	Pouze `client_id`. Klientské tajemství není k dispozici; PKCE S256 je povinné.
Confidential	Aplikace na straně serveru, kde lze tajemství uložit mimo uživatelovo zařízení a klientský kód.	`client_id` a `client_secret`.

Typ OAuth klienta je nezávislý na tom, zda je aplikace publikovaná. Například soukromá mobilní aplikace je veřejný OAuth klient bez tajemství.

Redirect URI

Uveďte každou URL, na kterou může Planfix vrátit uživatele po přihlášení.

Pro webovou službu používejte https.
http je povoleno pouze pro loopback adresy jako localhost a 127.0.0.1.
Klient může pro loopback adresu použít dynamické porty, ale schéma, host, cesta a query se musí shodovat.
Nepoužívejte zástupné znaky, URL fragmenty ani redirect URI, která nekontrolujete.

Scopes

Scopes definují maximální oprávnění aplikace. Požadujte pouze úrovně přístupu, které potřebujete, ze REST API scope list.

Aplikační scopes nenahrazují běžná uživatelská oprávnění. I pokud je scope udělen, aplikace může pracovat pouze s daty dostupnými danému uživateli.

Změna redirect URI nebo scopes vytvoří novou verzi pro schválení. Dříve připojené účty musí novou verzi zkontrolovat a schválit a uživatelé se budou muset připojit znovu.

Připojení zákaznického účtu

Soukromá aplikace vlastněná partnerem musí být v každém účtu explicitně schválena administrátorem.

Otevřete aplikaci ve svém partnerském účtu.
V sekci s odkazem pro schválení zadejte název zákaznického účtu.
Zkopírujte vygenerovaný odkaz a pošlete ho administrátorovi toho účtu.
Požádejte administrátora, aby ověřil vlastníka, redirect URI a scopes a následně aplikaci schválil.
Po schválení mohou uživatelé v účtu dokončit OAuth autorizaci. Každý uživatel souhlasí samostatně za sebe.

Odkaz otevře Account management → API → OAuth and MCP applications a zobrazí požadovanou aplikaci.

Administrátor, který zároveň připojuje aplikaci, může zvolit Approve and connect.

Soukromé a publikované aplikace

Stav	Jak se přidává do účtu
Private	Vždy vyžaduje explicitní schválení administrátorem každého účtu.
Published	Dostupná bez samostatného schválení, pokud je v účtu politika Allow published applications. Přesto vyžaduje schválení, když je politika Approved applications only.

Publikace je samostatné hodnocení Planfixu. Před podáním aplikace připravte jasný název a popis, minimální sadu scopes, funkční redirect URI a uživatelskou dokumentaci k připojení a odstranění integrace. Pro postup publikace kontaktujte Planfix Support.

Adresy pro připojení

Používejte globální OAuth endpointy:

Účel	Adresa
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`

Nepřidávejte název účtu do globální URL. Účet vybírá uživatel na stránce Planfixu. Kompletní protokol, včetně resource, PKCE, obnovy tokenu a odvolání, je popsán v OAuth 2.0 pro aplikace.

Správa aplikace

Partner může:

upravit název a popis;
změnit redirect URI a scopes;
zakázat a znovu povolit aplikaci;
otočit client secret u confidential aplikace;
vygenerovat odkaz pro schválení aplikace pro konkrétní účet.

Po otočení tajemství přestane staré client_secret okamžitě fungovat. Aktualizujte tajemství na serveru integrace a nikdy ho neposílejte uživatelům.

Zakázání aplikace zablokuje OAuth autorizaci a vydané tokeny ve všech účtech. Tato akce ovlivní všechny zákazníky používající aplikaci.

Doporučení před spuštěním

Používejte Authorization Code s PKCE S256 a validujte state.
Požadujte pouze potřebné scopes.
Po přihlášení ukažte uživateli vybraný účet.
Zpracujte rotaci refresh tokenu: po úspěšné obnově již předchozí refresh token není platný.
Nezapisujte tokeny, autorizační kódy, code_verifier ani client secret do logů.
Zdokumentujte, jak mohou uživatelé integraci odpojit a požádat o smazání svých dat.
Otestujte scénáře odvolání schválení, zakázání aplikace a opětovného připojení.