Enregistrer une application partenaire avec OAuth et gérer les applications installées

Une application OAuth permet à d’autres organisations Flowella de connecter votre produit à leur compte sans partager de clés API. Chaque organisation approuve votre application sur un écran de consentement et peut la révoquer à tout moment. Cette page explique aux partenaires comment enregistrer une application et utiliser OAuth, et aux clients comment examiner et révoquer les applications qu’ils ont installées. Pour vos propres scripts et intégrations, une clé API est plus simple.

Fonctionnement

Flowella prend en charge trois types d’autorisation OAuth : le code d’autorisation avec PKCE pour les organisations de vos clients, les identifiants client (client credentials) pour votre propre organisation, et les jetons d’actualisation. La séquence montre comment un client installe votre application avec le code d’autorisation.

Avant de commencer

Vous devez avoir le rôle Owner ou Admin dans l’organisation qui sera propriétaire de l’application. Les autres rôles voient Developer apps dans le menu, mais la liste ne se charge pas pour eux.
Votre application a besoin d’une adresse de rappel (redirect URI) capable de recevoir le code d’autorisation.
Votre application doit envoyer une valeur state et un code_challenge PKCE généré avec S256 à chaque demande d’autorisation.

Enregistrer une application

Ouvrez Developer apps

Accédez à Settings, puis sélectionnez Developer apps dans le groupe Developer.

Lancez une nouvelle application

Sélectionnez Create app. La boîte de dialogue Create developer app s’ouvre.

Nommez l'application

Dans App name, saisissez le nom sous lequel les clients connaissent votre produit, jusqu’à 120 caractères, par exemple Acme CRM connector.

Ajoutez les redirect URIs

Dans Redirect URIs, saisissez chaque adresse de rappel sur sa propre ligne, jusqu’à 20. Lors de l’autorisation, la redirect_uri envoyée par votre application doit correspondre exactement à l’une d’elles.

Choisissez les scopes

Sous Scopes, les scopes de lecture sont cochés pour vous. Cochez tout autre scope dont votre application a besoin et décochez ceux qui ne lui servent pas. Ce sont les scopes maximum que votre application pourra demander. Voir Scopes.

Créez l'application et copiez le secret

Sélectionnez Create app. La boîte de dialogue Save your client secret affiche le client secret, qui commence par flc_. Sélectionnez Copy, stockez le secret sur votre serveur, puis sélectionnez Done.

Flowella n’affiche le client secret qu’une seule fois, et vous ne pouvez pas le réinitialiser. Si vous le perdez, vous devez supprimer l’application et en enregistrer une nouvelle, et chaque organisation qui utilise votre application doit approuver la nouvelle.

Vous ne pouvez pas modifier le nom, les redirect URIs ou les scopes d’une application après sa création. Pour les modifier, enregistrez une nouvelle application. La liste Developer apps affiche pour chaque application son Name, son Client ID (qui commence par floa_), ses Redirect URIs et sa date Created, avec un bouton Delete sous Actions.

Faire passer un client par l’autorisation

Redirigez le navigateur du client vers l’endpoint d’autorisation sur l’hôte de l’application 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

Paramètre	Obligatoire	Valeur
`response_type`	Oui	`code`
`client_id`	Oui	Le client ID de votre application.
`redirect_uri`	Oui	L’une des redirect URIs enregistrées de l’application, à l’identique.
`state`	Oui	Une valeur aléatoire que votre application vérifie au retour du client.
`code_challenge`	Oui	Le hachage SHA-256, encodé en base64url, d’un `code_verifier` aléatoire que votre application conserve.
`code_challenge_method`	Non	`S256`, la seule méthode prise en charge et la valeur par défaut.
`scope`	Non	Des scopes séparés par des espaces, tous compris dans les scopes de l’application. Sans ce paramètre, l’application n’obtient que les scopes de lecture qui lui sont autorisés.
`publicOrgId`	Non	Le numéro d’organisation à six chiffres figurant dans l’adresse web Flowella du client. Sans ce paramètre, Flowella utilise l’organisation dans laquelle la personne travaille actuellement.

Si la requête n’est pas valide, Flowella affiche une erreur au lieu de l’écran de consentement et ne redirige pas. C’est le cas, par exemple, lorsque la redirect_uri ne correspond pas ou qu’un scope n’est pas autorisé.

Ce que voit le client

Si la personne n’est pas connectée, Flowella lui demande d’abord de se connecter.
La personne doit être Owner ou Admin de l’organisation. Toute autre personne voit l’erreur Owner or admin role required to authorize apps.
L’écran Authorize app affiche votre Client ID: et les Requested scopes:. Si votre application n’a pas envoyé de scope, il indique This app will receive its default allowed scopes.
La personne sélectionne Allow access ou Deny.

Allow access renvoie le navigateur vers votre redirect_uri avec code et state dans la chaîne de requête. Le code est valable 10 minutes et ne fonctionne qu’une fois. Deny renvoie le navigateur vers votre redirect_uri avec error=access_denied, un error_description et votre state.

Échanger le code contre des jetons

Votre serveur échange le code auprès de l’endpoint de jetons. Authentifiez-vous avec votre client ID et votre secret, soit avec l’authentification HTTP Basic, soit en envoyant client_id et client_secret dans le corps. Le corps peut être encodé en formulaire ou en 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 réponse contient les jetons :

{
  "access_token": "fla_xxxxxxxxxxxxxxxx",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "flr_xxxxxxxxxxxxxxxx",
  "scope": "messages:read contacts:read"
}

Jeton	Commence par	Validité
Jeton d’accès	`fla_`	1 heure
Jeton d’actualisation	`flr_`	30 jours, et seulement jusqu’à sa première utilisation

L’endpoint de jetons accepte 30 requêtes par minute pour chaque client ID et adresse IP. Au-delà, il renvoie 429 avec un en-tête Retry-After.

Appeler l’API

Envoyez le jeton d’accès comme jeton bearer, exactement comme une clé API :

Authorization: Bearer fla_xxxxxxxxxxxxxxxx

Le jeton ne fonctionne que pour l’organisation qui l’a approuvé, et uniquement pour les scopes accordés. Une requête en dehors de ces scopes renvoie 403 INSUFFICIENT_SCOPE. Chaque jeton d’accès a sa propre limite de débit. Voir l’introduction à l’API.

POST /v1/templates/send n’accepte que les clés API et refuse les jetons d’accès OAuth avec 401.

Actualiser un jeton d’accès

Avant l’expiration du jeton d’accès, demandez-en un nouveau avec grant_type=refresh_token, le refresh_token et l’authentification de votre client. La réponse contient un nouveau jeton d’accès et un nouveau jeton d’actualisation, et l’ancien jeton d’actualisation cesse de fonctionner. Si quelqu’un présente un jeton d’actualisation déjà utilisé, Flowella révoque tous les jetons émis à partir de cette autorisation, et le client doit à nouveau approuver votre application.

Accéder à votre propre organisation

Pour appeler l’API pour l’organisation propriétaire de l’application, utilisez grant_type=client_credentials avec l’authentification de votre client et un scope facultatif. Vous obtenez un jeton d’accès sans jeton d’actualisation. Votre application apparaît alors sous Installed apps dans votre propre organisation.

Révoquer ou inspecter un jeton

Endpoint	Ce qu’il fait
`POST https://app.flowella.io/api/oauth/revoke`	Révoque le `token` envoyé, ainsi que tous les jetons émis avec lui.
`POST https://app.flowella.io/api/oauth/introspect`	Indique si le `token` est `active`, avec son `scope`, son `client_id`, son `organization_id` et son heure d’expiration.

Les deux endpoints nécessitent l’authentification de votre client. Le document de découverte à l’adresse https://app.flowella.io/.well-known/oauth-authorization-server liste tous les endpoints et options pris en charge.

Examiner et révoquer les applications installées

Les clients gèrent les applications qu’ils ont approuvées sous Installed apps. Vous devez avoir le rôle Owner ou Admin. La liste affiche :

Colonne	Ce qu’elle affiche
App	Le nom de l’application, avec son client ID en dessous.
Scopes	Les scopes accordés à l’application.
Installed	La date de la première approbation de l’application.
Actions	Revoke, ou un badge Revoked.

Pour révoquer une application :

Accédez à Settings, puis sélectionnez Installed apps dans le groupe Developer.
Sélectionnez Revoke sur la ligne de l’application.
Confirmez l’invite Revoke this install? Existing tokens stop working.

Les jetons de l’application cessent immédiatement de fonctionner, et elle ne peut pas les actualiser. La ligne reste dans la liste avec un badge Revoked. Pour redonner l’accès à l’application, un Owner ou un Admin l’approuve à nouveau sur l’écran de consentement.

Révoquer votre propre application dans votre propre organisation n’empêche pas l’autorisation par identifiants client : l’application peut demander un nouveau jeton, ce qui réactive l’installation. Pour couper complètement l’accès de votre propre application, supprimez-la sous Developer apps.

Supprimer une application

Dans Developer apps, sélectionnez Delete sur la ligne de l’application et confirmez Delete this app and its tokens? Flowella supprime l’application, son installation dans chaque organisation qui l’a approuvée, et tous ses jetons. Cette action est irréversible.

Dépannage

Could not load developer apps ou Could not load installed apps

Seuls les Owners et les Admins peuvent voir ces écrans. Demandez à un Owner ou à un Admin de gérer l’application pour vous. Les rôles ne peuvent pas être modifiés dans l’application : voir Modifier le rôle d’une personne.

Redirect URI non concordante

La redirect_uri de la requête doit correspondre exactement à l’une des redirect URIs enregistrées de l’application, y compris le schéma, le chemin et l’éventuelle barre oblique finale. La même valeur doit être renvoyée lors de l’échange du code. Vous ne pouvez pas modifier les redirect URIs d’une application : enregistrez une nouvelle application si vous en avez besoin d’une autre.

invalid_scope

Un scope demandé est mal orthographié ou ne fait pas partie des scopes de l’application. Ne demandez que les scopes que vous avez cochés lors de l’enregistrement de l’application.

Owner or admin role required to authorize apps

La personne qui approuve l’application n’est ni Owner ni Admin de l’organisation. Demandez à un Owner ou à un Admin de terminer l’autorisation.

L'échange du code échoue

Les messages Authorization code expired et Authorization code already used signifient que vous devez recommencer l’autorisation : les codes durent 10 minutes et ne fonctionnent qu’une fois. PKCE verification failed signifie que le code_verifier ne correspond pas au code_challenge que vous avez envoyé.

Voir aussi

Introduction à l'API

Authentification, scopes, limites de débit et erreurs.

Developer hub

Requêtes API récentes, guides de démarrage rapide et API sandbox.

Clés API

Un accès plus simple pour vos propres scripts et intégrations.

Référence des webhooks

Réagissez aux événements dans les organisations qui installent votre application.

Premiers pas

Essentiels

Utiliser l'application

Paramètres

Configuration Meta et WhatsApp

Intégration HubSpot

Flows et campagnes

Référence API

Dépannage

Journal des modifications

Enregistrer une application partenaire avec OAuth et gérer les applications installées

Fonctionnement

Avant de commencer

Enregistrer une application

Faire passer un client par l’autorisation

Ce que voit le client

Échanger le code contre des jetons

Appeler l’API

Actualiser un jeton d’accès

Accéder à votre propre organisation

Révoquer ou inspecter un jeton

Examiner et révoquer les applications installées

Supprimer une application

Dépannage

Voir aussi

Introduction à l'API

Developer hub

Clés API

Référence des webhooks

​Fonctionnement

​Avant de commencer

​Enregistrer une application

​Faire passer un client par l’autorisation

​Ce que voit le client

​Échanger le code contre des jetons

​Appeler l’API

​Actualiser un jeton d’accès

​Accéder à votre propre organisation

​Révoquer ou inspecter un jeton

​Examiner et révoquer les applications installées

​Supprimer une application

​Dépannage

​Voir aussi

Introduction à l'API

Developer hub

Clés API

Référence des webhooks

Fonctionnement

Avant de commencer

Enregistrer une application

Faire passer un client par l’autorisation

Ce que voit le client

Échanger le code contre des jetons

Appeler l’API

Actualiser un jeton d’accès

Accéder à votre propre organisation

Révoquer ou inspecter un jeton

Examiner et révoquer les applications installées

Supprimer une application

Dépannage

Voir aussi