> ## Documentation Index > Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt > Use this file to discover all available pages before exploring further. # Registrare un'app partner con OAuth e gestire le app installate > Registrate un'app OAuth, guidate i clienti attraverso la schermata di consenso di Flowella, scambiate i codici con i token e verificate o revocate le app installate nella vostra organizzazione. Un'app OAuth consente ad altre organizzazioni Flowella di collegare il vostro prodotto al loro account senza condividere chiavi API. Ogni organizzazione approva la vostra app in una schermata di consenso e può revocarla in qualsiasi momento. Questa pagina spiega ai partner come registrare un'app e usare OAuth, e ai clienti come verificare e revocare le app che hanno installato. Per i vostri script e le vostre integrazioni, una [chiave API](https://knowledge.flowella.io/it/settings/api-keys.md) è più semplice. ## Come funziona Flowella supporta tre grant OAuth: authorisation code con PKCE per le organizzazioni dei clienti, client credentials per la vostra organizzazione e refresh token. La sequenza mostra come un cliente installa la vostra app con il grant authorisation code. ```mermaid theme={null} sequenceDiagram participant Admin as Admin del cliente participant App as La vostra app participant Flowella App->>Admin: Reindirizza all'URL di autorizzazione di Flowella Admin->>Flowella: Apre l'URL di autorizzazione Flowella->>Admin: Mostra la schermata di consenso Admin->>Flowella: Seleziona Allow access Flowella->>App: Reindirizza indietro con un codice App->>Flowella: Scambia il codice e il verifier Flowella->>App: Access token e refresh token App->>Flowella: Chiama l'API con l'access token ``` ## Prima di iniziare * Serve il ruolo **Owner** o **Admin** nell'organizzazione che sarà proprietaria dell'app. Gli altri ruoli vedono **Developer apps** nel menu, ma per loro l'elenco non si carica. * La vostra app ha bisogno di un indirizzo di callback (redirect URI) in grado di ricevere il codice di autorizzazione. * La vostra app deve inviare un valore `state` e un `code_challenge` PKCE generato con `S256` a ogni richiesta di autorizzazione. ## Registrare un'app **1. Aprite Developer apps** Andate su **Settings**, poi selezionate **Developer apps** nel gruppo **Developer**. **2. Avviate una nuova app** Selezionate **Create app**. Si apre la finestra di dialogo **Create developer app**. **3. Assegnate un nome all'app** In **App name**, inserite il nome con cui i clienti conoscono il vostro prodotto, fino a 120 caratteri, ad esempio `Acme CRM connector`. **4. Aggiungete i redirect URI** In **Redirect URIs**, inserite ogni indirizzo di callback su una riga separata, fino a 20. Durante l'autorizzazione, il `redirect_uri` inviato dalla vostra app deve corrispondere esattamente a uno di questi. **5. Scegliete gli scope** Sotto **Scopes**, gli scope di lettura sono già selezionati. Selezionate gli altri scope necessari alla vostra app e deselezionate quelli che non servono. Questi sono il massimo che la vostra app potrà mai richiedere. Consultate [Scopes](https://knowledge.flowella.io/it/api-reference/introduction.md#scope). **6. Create l'app e copiate il secret** Selezionate **Create app**. La finestra di dialogo **Save your client secret** mostra il client secret, che inizia con `flc_`. Selezionate **Copy**, conservate il secret sul vostro server, poi selezionate **Done**. > [!WARNING] > > Flowella mostra il client secret una sola volta e non potete reimpostarlo. Se lo perdete, dovete eliminare l'app e registrarne una nuova, e ogni organizzazione che usa la vostra app dovrà approvare quella nuova. Non potete modificare il nome, i redirect URI o gli scope di un'app dopo averla creata. Per modificarli, registrate una nuova app. L'elenco **Developer apps** mostra per ogni app **Name**, **Client ID** (inizia con `floa_`), **Redirect URIs** e data **Created**, con un pulsante **Delete** sotto **Actions**. ## Guidare un cliente attraverso l'autorizzazione Indirizzate il browser del cliente all'endpoint di autorizzazione sull'host dell'app Flowella: ```text theme={null} https://app.flowella.io/api/oauth/authorize?response_type=code&client_id=floa_xxxx&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback&scope=messages%3Aread%20contacts%3Aread&state=RANDOM_STATE&code_challenge=CODE_CHALLENGE&code_challenge_method=S256 ``` | Parametro | Obbligatorio | Valore | | - | - | - | | `response_type` | Sì | `code` | | `client_id` | Sì | Il client ID della vostra app. | | `redirect_uri` | Sì | Uno dei redirect URI registrati dell'app, esattamente. | | `state` | Sì | Un valore casuale che la vostra app controlla quando il cliente ritorna. | | `code_challenge` | Sì | L'hash SHA-256 codificato in base64url di un `code_verifier` casuale conservato dalla vostra app. | | `code_challenge_method` | No | `S256`, l'unico metodo supportato e quello predefinito. | | `scope` | No | Scope separati da spazi, tutti compresi negli scope dell'app. Se assente, l'app riceve solo gli scope di lettura consentiti. | | `publicOrgId` | No | Il numero di sei cifre dell'organizzazione presente nell'indirizzo web di Flowella del cliente. Se assente, Flowella usa l'organizzazione in cui la persona sta lavorando in quel momento. | Se la richiesta non è valida, Flowella mostra un errore al posto della schermata di consenso e non effettua il reindirizzamento. Succede, ad esempio, quando il `redirect_uri` non corrisponde o uno scope non è consentito. ### Cosa vede il cliente 1. Se la persona non ha effettuato l'accesso, Flowella le chiede prima di accedere. 2. La persona deve essere **Owner** o **Admin** dell'organizzazione. Chiunque altro vede l'errore `Owner or admin role required to authorize apps`. 3. La schermata **Authorize app** mostra il vostro **Client ID:** e i **Requested scopes:**. Se la vostra app non ha inviato uno `scope`, riporta **This app will receive its default allowed scopes.** 4. La persona seleziona **Allow access** o **Deny**. **Allow access** indirizza il browser al vostro `redirect_uri` con `code` e `state` nella query string. Il codice è valido per 10 minuti e funziona una sola volta. **Deny** indirizza il browser al vostro `redirect_uri` con `error=access_denied`, una `error_description` e il vostro `state`. ## Scambiare il codice con i token Il vostro server scambia il codice presso l'endpoint dei token. Autenticatevi con il vostro client ID e secret, tramite autenticazione HTTP Basic oppure come `client_id` e `client_secret` nel corpo della richiesta. Il corpo può essere codificato come form oppure JSON. ```bash theme={null} curl -X POST "https://app.flowella.io/api/oauth/token" \ -u "$FLOWELLA_CLIENT_ID:$FLOWELLA_CLIENT_SECRET" \ -d grant_type=authorization_code \ -d code="$CODE" \ -d redirect_uri="https://example.com/oauth/callback" \ -d code_verifier="$CODE_VERIFIER" ``` La risposta contiene i token: ```json theme={null} { "access_token": "fla_xxxxxxxxxxxxxxxx", "token_type": "bearer", "expires_in": 3600, "refresh_token": "flr_xxxxxxxxxxxxxxxx", "scope": "messages:read contacts:read" } ``` | Token | Inizia con | Validità | | - | - | - | | Access token | `fla_` | 1 ora | | Refresh token | `flr_` | 30 giorni, e solo finché non viene usato una volta | L'endpoint dei token accetta 30 richieste al minuto per ogni client ID e indirizzo IP. Oltre questa soglia, restituisce `429` con un'intestazione `Retry-After`. ## Chiamare l'API Inviate l'access token come bearer token, esattamente come una chiave API: ```http theme={null} Authorization: Bearer fla_xxxxxxxxxxxxxxxx ``` Il token funziona solo per l'organizzazione che lo ha approvato e solo per gli scope concessi. Una richiesta al di fuori di questi scope restituisce `403 INSUFFICIENT_SCOPE`. Ogni access token ha il proprio limite di frequenza. Consultate l'[introduzione all'API](https://knowledge.flowella.io/it/api-reference/introduction.md). > [!NOTE] > > `POST /v1/templates/send` accetta solo chiavi API e rifiuta gli access token OAuth con `401`. ### Rinnovare un access token Prima che l'access token scada, richiedetene uno nuovo con `grant_type=refresh_token`, il `refresh_token` e l'autenticazione del vostro client. La risposta contiene un nuovo access token e un nuovo refresh token, e il vecchio refresh token smette di funzionare. Se qualcuno presenta un refresh token già usato, Flowella revoca tutti i token emessi da quell'autorizzazione e il cliente deve approvare di nuovo la vostra app. ### Accedere alla vostra organizzazione Per chiamare l'API per l'organizzazione proprietaria dell'app, usate `grant_type=client_credentials` con l'autenticazione del vostro client e uno `scope` facoltativo. Ottenete un access token senza refresh token. La vostra app compare quindi sotto **Installed apps** nella vostra organizzazione. ### Revocare o ispezionare un token | Endpoint | Cosa fa | | - | - | | `POST https://app.flowella.io/api/oauth/revoke` | Revoca il `token` inviato, insieme a tutti i token emessi con esso. | | `POST https://app.flowella.io/api/oauth/introspect` | Indica se il `token` è `active`, con il suo `scope`, `client_id`, `organization_id` e la scadenza. | Entrambi gli endpoint richiedono l'autenticazione del vostro client. Il documento di discovery su `https://app.flowella.io/.well-known/oauth-authorization-server` elenca tutti gli endpoint e le opzioni supportate. ## Verificare e revocare le app installate I clienti gestiscono le app che hanno approvato sotto **Installed apps**. Serve il ruolo **Owner** o **Admin**. L'elenco mostra: | Colonna | Cosa mostra | | - | - | | **App** | Il nome dell'app, con il suo client ID sotto. | | **Scopes** | Gli scope concessi all'app. | | **Installed** | Quando l'app è stata approvata per la prima volta. | | **Actions** | **Revoke**, oppure un badge **Revoked**. | Per revocare un'app: 1. Andate su **Settings**, poi selezionate **Installed apps** nel gruppo **Developer**. 2. Selezionate **Revoke** nella riga dell'app. 3. Confermate il messaggio **Revoke this install? Existing tokens stop working.** I token dell'app smettono subito di funzionare e l'app non può rinnovarli. La riga resta nell'elenco con un badge **Revoked**. Per concedere di nuovo l'accesso all'app, un Owner o un Admin la approva di nuovo nella schermata di consenso. > [!NOTE] > > Revocare la vostra app nella vostra organizzazione non blocca il grant client credentials: l'app può richiedere un nuovo token, che riattiva l'installazione. Per bloccare completamente la vostra app, eliminatela sotto **Developer apps**. ## Eliminare un'app In **Developer apps**, selezionate **Delete** nella riga dell'app e confermate **Delete this app and its tokens?** Flowella rimuove l'app, la sua installazione in ogni organizzazione che l'ha approvata e tutti i suoi token. L'operazione non può essere annullata. ## Risoluzione dei problemi > **Could not load developer apps o Could not load installed apps** > > Solo Owner e Admin possono visualizzare queste schermate. Chiedete a un Owner o a un Admin di gestire l'app per voi. I ruoli non possono essere modificati nell'app: consultate [Change someone's role](https://knowledge.flowella.io/it/settings/team.md#cambiare-il-ruolo-di-una-persona). > **Redirect URI non corrispondente** > > Il `redirect_uri` nella richiesta deve corrispondere esattamente a uno dei redirect URI registrati dell'app, compresi schema, percorso ed eventuale barra finale. Lo stesso valore deve essere inviato di nuovo quando scambiate il codice. Non potete modificare i redirect URI di un'app, quindi registrate una nuova app se ve ne serve uno diverso. > **invalid\_scope** > > Uno scope richiesto è scritto male o non fa parte degli scope dell'app. Richiedete solo gli scope che avete selezionato quando avete registrato l'app. > **Owner or admin role required to authorize apps** > > La persona che approva l'app non è Owner o Admin dell'organizzazione. Chiedete a un Owner o a un Admin di completare l'autorizzazione. > **Lo scambio del codice non riesce** > > I messaggi `Authorization code expired` e `Authorization code already used` indicano che dovete avviare di nuovo l'autorizzazione: i codici durano 10 minuti e funzionano una sola volta. `PKCE verification failed` significa che il `code_verifier` non corrisponde al `code_challenge` che avete inviato. ## Risorse correlate > **[Introduzione all'API](https://knowledge.flowella.io/it/api-reference/introduction.md)** > > Autenticazione, scope, limiti di frequenza ed errori. > **[Developer hub](https://knowledge.flowella.io/it/settings/developer-hub.md)** > > Richieste API recenti, guide rapide e la API sandbox. > **[Chiavi API](https://knowledge.flowella.io/it/settings/api-keys.md)** > > Un accesso più semplice per i vostri script e le vostre integrazioni. > **[Riferimento webhook](https://knowledge.flowella.io/it/api-reference/webhooks.md)** > > Reagite agli eventi nelle organizzazioni che installano la vostra app. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.