Registrare un'app partner con OAuth e gestire le app installate

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 è 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.

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

Aprite Developer apps

Andate su Settings, poi selezionate Developer apps nel gruppo Developer.

Avviate una nuova app

Selezionate Create app. Si apre la finestra di dialogo Create developer app.

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.

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.

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.

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.

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:

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

Se la persona non ha effettuato l’accesso, Flowella le chiede prima di accedere.
La persona deve essere Owner o Admin dell’organizzazione. Chiunque altro vede l’errore Owner or admin role required to authorize apps.
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.
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.

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:

{
  "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:

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.

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:

Andate su Settings, poi selezionate Installed apps nel gruppo Developer.
Selezionate Revoke nella riga dell’app.
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.

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.

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

Autenticazione, scope, limiti di frequenza ed errori.

Developer hub

Richieste API recenti, guide rapide e la API sandbox.

Chiavi API

Un accesso più semplice per i vostri script e le vostre integrazioni.

Riferimento webhook

Reagite agli eventi nelle organizzazioni che installano la vostra app.

Per iniziare

Essenziali

Usare l'app

Impostazioni

Configurazione Meta e WhatsApp

Integrazione HubSpot

Flow e campagne

Riferimento API

Risoluzione problemi

Registro modifiche

Registrare un'app partner con OAuth e gestire le app installate

Come funziona

Prima di iniziare

Registrare un’app

Guidare un cliente attraverso l’autorizzazione

Cosa vede il cliente

Scambiare il codice con i token

Chiamare l’API

Rinnovare un access token

Accedere alla vostra organizzazione

Revocare o ispezionare un token

Verificare e revocare le app installate

Eliminare un’app

Risoluzione dei problemi

Risorse correlate

Introduzione all'API

Developer hub

Chiavi API

Riferimento webhook

​Come funziona

​Prima di iniziare

​Registrare un’app

​Guidare un cliente attraverso l’autorizzazione

​Cosa vede il cliente

​Scambiare il codice con i token

​Chiamare l’API

​Rinnovare un access token

​Accedere alla vostra organizzazione

​Revocare o ispezionare un token

​Verificare e revocare le app installate

​Eliminare un’app

​Risoluzione dei problemi

​Risorse correlate

Introduzione all'API

Developer hub

Chiavi API

Riferimento webhook

Come funziona

Prima di iniziare

Registrare un’app

Guidare un cliente attraverso l’autorizzazione

Cosa vede il cliente

Scambiare il codice con i token

Chiamare l’API

Rinnovare un access token

Accedere alla vostra organizzazione

Revocare o ispezionare un token

Verificare e revocare le app installate

Eliminare un’app

Risoluzione dei problemi

Risorse correlate