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 utilizza il flusso Authorization Code con obbligatorio PKCE S256. OAuth può essere utilizzato per connettersi al REST API o al Planfix MCP server.

Se vuoi connettere un client AI già pronto, inizia da Planfix MCP. Se gestisci l'accesso nel tuo account, vedi OAuth and MCP applications in an account. Partner e sviluppatori di integrazioni multi-account devono vedere OAuth applications for partners.

Opzioni di registrazione dell'applicazione

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

CIMD e DCR sono disponibili solo per connessioni MCP. Per la REST API, usa un'applicazione di proprietà dell'account o del 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.

Scopo	Indirizzo
Issuer	https://auth.planfix.com
Authorization	https://auth.planfix.com/oauth/authorize
Token	https://auth.planfix.com/oauth/token
Informazioni utente	https://auth.planfix.com/oauth/userinfo
Revoca token	https://auth.planfix.com/oauth/revoke
Registrazione dinamica client MCP	https://auth.planfix.com/oauth/register

I metadata dell'authorization server sono disponibili agli endpoint standard:

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

URI di redirect

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

Sono ammessi:

• 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 ammessi frammenti nell'URL né informazioni utente nell'URL.

Livelli di accesso

Un'applicazione riceve solo i livelli di accesso, o scopes, che sono stati autorizzati in anticipo. Vedi REST API access levels per l'elenco completo.

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

Le applicazioni gestite ricevono inoltre gli scope di servizio userinfo, openid e email.

Autorizzazione dell'utente

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

Esempio 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'esatto URL del server MCP:

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

Parametro	Descrizione
client_id	L'identificatore di un'applicazione registrata. Per CIMD, questo è l'URL del documento di metadata del client.
redirect_uri	Uno degli redirect URI consentiti.
response_type	Deve essere code.
scope	I permessi richiesti separati da spazi. Questo parametro è obbligatorio per la REST API. Un client MCP può ometterlo, nel qual caso vengono usati gli scope consentiti per l'applicazione.
state	Un valore casuale che protegge la richiesta da sostituzioni. L'applicazione deve validarlo dopo il redirect.
code_challenge	Base64url senza padding dell'hash SHA-256 di code_verifier.
code_challenge_method	È supportato solo S256.
resource	Per MCP, l'URL esatto https://mcp.planfix.com/mcp. Non inviare questo parametro per la REST API.

L'utente seleziona un account, effettua il login e rivede i permessi richiesti. Un'applicazione di proprietà dell'account apre direttamente il suo account proprietario. Se la policy di sicurezza richiede l'approvazione dell'amministratore, Planfix mostra il passo corrispondente. Un amministratore può approvare l'applicazione e connetterla in un'unica azione.

Dopo un'autorizzazione riuscita, 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 authorization code è monouso e rimane 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 public client invia la richiesta senza secret. Un confidential client si autentica anche usando client_secret_basic o 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 access token è valido per 24 ore. È vincolato all'utente, all'account, all'applicazione, agli scope e alla resource. Un token emesso 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.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Usa l'URL dell'account restituito quando il codice di autorizzazione è stato scambiato per i token. Sono disponibili solo i metodi coperti dagli scope concessi. I token OAuth sono soggetti al piano dell'account e ai normali REST API limits.

Informazioni sull'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 per i Dipendenti dell'account. Planfix non emette un id_token; richiedi i dati utente tramite userinfo invece.

Rinnovo dei 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 la stessa resource. Un confidential client deve autenticarsi usando il proprio secret.

Planfix restituisce un nuovo access token e un nuovo refresh token. Il refresh token precedente diventa immediatamente invalido, quindi l'applicazione deve sostituire il valore memorizzato in modo atomico.

Revoca di un token

Un client può revocare un refresh token 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 Session management nella propria scheda utente. Un amministratore può revocare l'approvazione di un'applicazione di terze parti per l'intero account. Vedi OAuth and MCP applications in an account.

Compatibilità con integrazioni esistenti

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

Usa gli endpoint globali per le nuove integrazioni. Supportano la discovery dei metadata standard, la selezione dell'account e MCP. Non mescolare endpoint globali e tenant all'interno della stessa sessione OAuth.

Raccomandazioni di sicurezza

• Usa sempre PKCE S256 e valida state.
• Usa un public client senza secret per applicazioni mobile, desktop e web in browser.
• Usa un confidential client solo quando il secret può essere memorizzato in modo sicuro su un server.
• Richiedi il set minimo di scope necessario.
• Non scrivere access token, refresh token, authorization code, code_verifier o client secret nei log.
• Memorizza refresh token e client secret in archivi cifrati.
• Valida iss nella risposta e accetta solo l'issuer Planfix previsto.

Errori possibili

Errore	Causa
invalid_client	Il client è sconosciuto o disabilitato, il client secret è errato, oppure l'applicazione non è disponibile nell'account selezionato.
invalid_grant	L'autorization code o il refresh token è invalido, scaduto, già usato o non corrisponde al client, al redirect URI, ai dati PKCE o alla resource.
invalid_scope	La richiesta contiene uno scope non consentito per l'applicazione.
invalid_target	La resource non è supportata o è cambiata tra le richieste.
access_denied	L'utente ha rifiutato la connessione o la policy dell'account non consente l'applicazione.
HTTP 401, invalid_token	L'access token è sconosciuto, scaduto o revocato.
HTTP 403, insufficient_scope	Il token non contiene lo scope richiesto per l'operazione.

Vai a

• Planfix MCP
• OAuth and MCP applications in an account
• OAuth applications for partners
• REST API
• REST API Authorization
• REST API: Access Levels List – scope