Applicazioni OAuth per partner

Un'applicazione OAuth di proprietà del partner è pensata per un'integrazione che si connette a più account Planfix. Le stesse credenziali dell'applicazione sono usate per tutti gli account dei clienti, mentre ogni account controlla l'ammissione separatamente e ogni utente acconsente alla propria connessione.

Se un'integrazione è destinata a un solo account, è più semplice creare un'applicazione di proprietà dell'account.

Creazione di un'applicazione

Apri il tuo account partner.
Vai a OAuth applications.
Seleziona Create application.
Inserisci il nome e la descrizione che vedranno gli utenti e gli amministratori.
Seleziona il tipo di client OAuth.
Aggiungi gli URI di redirect.
Seleziona gli scope minimi richiesti per la REST API.
Salva l'applicazione e copia le sue credenziali.

Una nuova applicazione è privata e richiede approvazione esplicita in ogni account a cui si collega.

Tipo di client OAuth

Tipo	Applicazioni previste	Credenziali
Public	Applicazioni mobile, desktop e browser, e client MCP locali.	Un solo `client_id`. Non c'è client secret; PKCE S256 è obbligatorio.
Confidential	Applicazioni lato server dove il secret può essere conservato al di fuori del dispositivo dell'utente e codice lato client.	Un `client_id` e un `client_secret`.

Il tipo di client OAuth è distinto dal fatto che un'applicazione sia pubblicata. Per esempio, un'app mobile privata è un client OAuth pubblico senza secret.

URI di redirect

Specifica ogni URL al quale Planfix può reindirizzare un utente dopo l'accesso.

Usa https per un servizio web.
http è consentito solo per indirizzi loopback come localhost e 127.0.0.1.
Un client può usare una porta dinamica per un indirizzo loopback, ma lo schema, l'host, il percorso e la query devono corrispondere.
Non usare wildcard, frammenti URL o URI di redirect che non controlli.

Scopes

Gli scope definiscono i permessi massimi dell'applicazione. Richiedi solo i livelli di accesso necessari dalla REST API scope list.

Gli scope dell'applicazione non sostituiscono i permessi normali dell'utente. Anche quando uno scope è concesso, l'applicazione può operare solo con i dati disponibili a quell'utente.

La modifica degli URI di redirect o degli scope crea una nuova versione di approvazione. Gli account precedentemente connessi devono rivedere e approvare la nuova versione e gli utenti devono connettersi di nuovo.

Collegamento di un account cliente

Un'applicazione di proprietà del partner privata deve essere approvata esplicitamente da un amministratore in ogni account.

Apri l'applicazione nel tuo account partner.
Nell'area del link di approvazione, inserisci il nome dell'account cliente.
Copia il link generato e invialo a un amministratore di quell'account.
Chiedi all'amministratore di verificare il proprietario, gli URI di redirect e gli scope, quindi di approvare l'applicazione.
Dopo l'approvazione, gli utenti nell'account possono completare l'autorizzazione OAuth. Ogni utente acconsente separatamente per conto proprio.

Il link apre Account management → API → OAuth and MCP applications e mostra l'applicazione richiesta.

Un amministratore che sta inoltre collegando l'applicazione può selezionare Approve and connect.

Applicazioni private e pubblicate

Stato	Come viene ammessa in un account
Private	Richiede sempre approvazione esplicita da parte di un amministratore di ogni account.
Published	Disponibile senza approvazione separata quando la policy dell'account è Allow published applications. Richiede comunque approvazione quando la policy è Approved applications only.

La pubblicazione è una revisione separata di Planfix. Prima di inviare un'applicazione, prepara un nome e una descrizione chiari, un set minimo di scope, URI di redirect funzionanti e documentazione per gli utenti su come collegare e rimuovere l'integrazione. Contatta il Supporto Planfix per la procedura di pubblicazione.

Indirizzi di connessione

Usa gli endpoint OAuth globali:

Scopo	Indirizzo
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`

Non aggiungere il nome dell'account a un URL globale. L'utente seleziona l'account in una pagina Planfix. Il protocollo completo, incluso resource, PKCE, refresh dei token e revoca, è descritto in OAuth 2.0 per le applicazioni.

Gestione di un'applicazione

Un partner può:

modificare nome e descrizione;
cambiare gli URI di redirect e gli scope;
disabilitare e riabilitare l'applicazione;
ruotare il client secret di un'applicazione confidential;
generare un link di approvazione dell'applicazione per uno specifico account.

Dopo la rotazione del secret, il vecchio client secret smette di funzionare immediatamente. Aggiorna il secret sul server dell'integrazione e non inviarlo mai agli utenti.

Disabilitare un'applicazione blocca l'autorizzazione OAuth e i token emessi in ogni account. Questa azione influisce su tutti i clienti che usano l'applicazione.

Raccomandazioni prima del lancio

Usa Authorization Code con PKCE S256 e valida il state.
Richiedi solo gli scope necessari.
Mostra l'account selezionato all'utente dopo l'accesso.
Gestisci la rotazione del refresh token: dopo un refresh riuscito, il refresh token precedente non è più valido.
Non scrivere token, authorization code, code_verifier o client secret nei log.
Documenta come gli utenti possono scollegare l'integrazione e richiedere la cancellazione dei loro dati.
Testa gli scenari di revoca dell'approvazione, disabilitazione dell'applicazione e riconnessione.