Skip to content

OAuth 2.0 per le applicazioni

OAuth 2.0 consente a un'applicazione di accedere a Planfix per conto di un utente senza richiedere o memorizzare la password dell'utente.

Planfix usa il flusso Authorization Code con PKCE S256 obbligatorio. OAuth può essere usato per connettersi a REST API o al server MCP di Planfix.

Se vuoi connettere un client AI già pronto, inizia da Planfix MCP. Se gestisci gli accessi nel tuo account, consulta Applicazioni OAuth e MCP in un account. I partner e gli sviluppatori di integrazioni multi-account possono consultare Applicazioni OAuth per partner.

Opzioni di registrazione dell'applicazione

Opzione Quando usarla Dove funziona
Applicazione di proprietà dell'account L'integrazione è destinata a un solo account e il client richiede un client_id predefinito. Solo nell'account proprietario.
Applicazione di proprietà di un partner La stessa applicazione deve connettersi a più account cliente. Negli account in cui è consentito dai criteri di sicurezza o da un amministratore.
Registrazione automatica del client MCP Il client MCP supporta un Client ID Metadata Document (CIMD) o la Dynamic Client Registration (DCR). La registrazione non concede di per sé l'accesso all'account. L'applicazione deve comunque essere autorizzata nell'account selezionato.

CIMD e DCR sono disponibili solo per le connessioni MCP. Per la REST API, usa un'applicazione di proprietà dell'account o di un partner.

Endpoint OAuth

Le nuove integrazioni dovrebbero usare gli endpoint globali. Il nome dell'account non è incluso in questi URL: l'utente seleziona un account durante l'autorizzazione.




I metadati del server di autorizzazione sono disponibili agli endpoint standard:


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


URI di reindirizzamento

Un URI di reindirizzamento deve essere registrato nelle impostazioni dell'applicazione. Il valore inviato nella richiesta di autorizzazione deve corrispondere a un URI registrato.

Sono consentiti:

  • URL https;
  • URL http solo per host loopback, come localhost o 127.0.0.1.

La porta può essere dinamica per un URI loopback, ma lo schema, l'host, il percorso e la query devono corrispondere. Non sono consentiti frammenti URL né informazioni utente nell'URL.

Livelli di accesso

Un'applicazione riceve solo i livelli di accesso, o scopes, autorizzati in anticipo. Consulta Livelli di accesso REST API per l'elenco completo.

L'insieme richiesto deve essere un sottoinsieme degli scope registrati per l'applicazione. Gli scope dell'applicazione non estendono le autorizzazioni dell'utente in Planfix: l'applicazione può accedere solo ai dati disponibili al Dipendente che l'ha connessa.

Le applicazioni gestite hanno accesso anche agli scope di servizio userinfo, openid e email.

Autorizzazione utente

Genera un code_verifier e la sua rappresentazione SHA-256, code_challenge, quindi apri l'endpoint di autorizzazione in un browser.

Esempio per la 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


Per MCP, aggiungi il parametro resource con l'URL esatto del server MCP:



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


Parametro Descrizione
client_id Identificativo di un'applicazione registrata. Per CIMD, è l'URL del documento dei metadati del client.
redirect_uri Uno degli URI di reindirizzamento consentiti.
response_type Deve essere code.
scope Le autorizzazioni richieste, separate da spazi. Questo parametro è obbligatorio per la REST API. Un client MCP può ometterlo; in tal caso vengono usati gli scope consentiti per l'applicazione.
state Un valore casuale che protegge la richiesta dalla sostituzione. L'applicazione deve convalidarlo dopo il reindirizzamento.
code_challenge Hash SHA-256 di code_verifier codificato in Base64url senza padding.
code_challenge_method È supportato solo S256.
resource Per MCP, l'URL esatto del server MCP. Non inviare questo parametro per la REST API.


Per MCP, usa resource=https://mcp.planfix.com/mcp.

L'utente seleziona un account, accede e controlla le autorizzazioni richieste. Un'applicazione di proprietà dell'account apre direttamente l'account proprietario. Se i criteri di sicurezza richiedono l'approvazione di un amministratore, Planfix mostra il passaggio corrispondente. Un amministratore può approvare l'applicazione e connetterla con un'unica operazione.

Dopo l'autorizzazione, Planfix reindirizza il browser a redirect_uri:



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


Un codice di autorizzazione può essere usato una sola volta ed è valido per 10 minuti.

Ottenere i token

Invia una richiesta POST a /oauth/token usando 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

Per MCP, ripeti il parametro resource con lo stesso valore usato nella richiesta di autorizzazione.

Un client pubblico invia la richiesta senza un segreto. Un client riservato esegue anche l'autenticazione usando client_secret_basic oppure i parametri client_id e client_secret nel corpo della richiesta.

Esempio di risposta:

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

Per la REST API, la risposta contiene anche account_name, account_domain e account_url. Memorizza questi valori e usa l'URL dell'account selezionato per le richieste REST API.

Un token di accesso è valido per 24 ore. È associato all'utente, all'account, all'applicazione, agli scope e alla risorsa. Un token rilasciato per MCP non può essere usato direttamente con la REST API e un token REST API non può essere usato con MCP.

Usare un token con la REST API

Invia il token nell'intestazione Authorization:



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


Usa il dominio dell'account restituito quando il codice di autorizzazione è stato scambiato con un token. Sono disponibili solo i metodi coperti dagli scope concessi. I token OAuth sono soggetti al piano dell'account e ai limiti standard della REST API.

Informazioni utente

La richiesta userinfo richiede lo scope openid:



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


Esempio di risposta quando è presente lo scope email:

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

L'autorizzazione OAuth globale è disponibile ai Dipendenti dell'account. Planfix non rilascia un id_token; richiedi invece i dati dell'utente tramite userinfo.

Aggiornare i token


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


Per MCP, invia di nuovo lo stesso resource. Un client riservato deve autenticarsi usando il proprio segreto.

Planfix restituisce un nuovo token di accesso e un nuovo token di aggiornamento. Il token di aggiornamento precedente diventa subito non valido, quindi l'applicazione deve sostituire atomicamente il valore memorizzato.

Revocare un token

Un client può revocare un token di aggiornamento tramite /oauth/revoke:



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

token=REFRESH_TOKEN
&client_id=CLIENT_ID


Un utente può anche rimuovere una connessione dalla sezione Gestione sessioni della propria scheda utente. Un amministratore può revocare l'approvazione di un'applicazione di terze parti per l'intero account. Consulta Applicazioni OAuth e MCP in un account.

Compatibilità con le integrazioni esistenti

Gli endpoint specifici del tenant, come https://account.planfix.com/api/v2/oauth/authorize, /token e /userinfo, continuano a funzionare per le integrazioni esistenti associate a un account specifico.

Usa gli endpoint globali per le nuove integrazioni. Supportano l'individuazione standard dei metadati, la selezione dell'account e MCP. Non combinare endpoint globali e specifici del tenant nella stessa sessione OAuth.

Raccomandazioni di sicurezza

  • Usa sempre PKCE S256 e convalida state.
  • Usa un client pubblico senza segreto per le applicazioni mobili, desktop e browser.
  • Usa un client riservato solo se il segreto può essere memorizzato in modo sicuro su un server.
  • Richiedi il numero minimo necessario di scope.
  • Non registrare nei log token di accesso, token di aggiornamento, codici di autorizzazione, code_verifier o segreti client.
  • Memorizza i token di aggiornamento e i segreti client in un archivio crittografato.
  • Convalida iss nella risposta e accetta solo l'issuer Planfix previsto.

Possibili errori

Errore Causa
invalid_client Il client è sconosciuto o disabilitato, il segreto client non è corretto oppure l'applicazione non è disponibile nell'account selezionato.
invalid_grant Il codice di autorizzazione o il token di aggiornamento non è valido, è scaduto, è già stato usato oppure non corrisponde al client, all'URI di reindirizzamento, ai dati PKCE o alla risorsa.
invalid_scope La richiesta contiene uno scope non consentito per l'applicazione.
invalid_target La resource non è supportata oppure è stata modificata tra una richiesta e l'altra.
access_denied L'utente ha rifiutato la connessione oppure i criteri dell'account non consentono l'applicazione.
HTTP 401, invalid_token Il token di accesso è sconosciuto, è scaduto o è stato revocato.
HTTP 403, insufficient_scope Il token non contiene lo scope richiesto per l'operazione.

Vai a