Applications OAuth pour les partenaires

Une application OAuth détenue par un partenaire est destinée à une intégration qui se connecte à plusieurs comptes Planfix. Les mêmes identifiants d'application sont utilisés pour tous les comptes clients, tandis que chaque compte contrôle l'admission séparément et chaque utilisateur consent à sa propre connexion.

Si une intégration est destinée à un seul compte, il est plus simple de créer une application détenue par le compte.

Création d'une application

Ouvrez votre compte partenaire.
Allez à Applications OAuth.
Sélectionnez Créer une application.
Saisissez le nom et la description que les utilisateurs et les administrateurs verront.
Sélectionnez le type de client OAuth.
Ajoutez les URI de redirection.
Sélectionnez les scopes minimaux nécessaires du REST API.
Enregistrez l'application et copiez ses identifiants.

Une nouvelle application est privée et nécessite une approbation explicite dans chaque compte auquel elle se connecte.

Type de client OAuth

Type	Applications visées	Identifiants
Public	Applications mobiles, de bureau et navigateur, et clients MCP locaux.	Un `client_id` uniquement. Il n'y a pas de secret client ; PKCE S256 est obligatoire.
Confidential	Applications côté serveur où le secret peut être stocké en dehors de l'appareil de l'utilisateur et du code côté client.	Un `client_id` et un `client_secret`.

Le type de client OAuth est distinct du fait qu'une application soit publiée ou non. Par exemple, une application mobile privée est un client OAuth public sans secret.

URI de redirection

Spécifiez chaque URL vers laquelle Planfix peut renvoyer un utilisateur après la connexion.

Utilisez https pour un service web.
http n'est autorisé que pour les adresses de loopback telles que localhost et 127.0.0.1.
Un client peut utiliser un port dynamique pour une adresse de loopback, mais le schéma, l'hôte, le chemin et la requête doivent correspondre.
N'utilisez pas de jokers, de fragments d'URL, ni d'URI de redirection que vous ne contrôlez pas.

Scopes

Les scopes définissent les permissions maximales de l'application. Demandez uniquement les niveaux d'accès requis depuis la liste des scopes REST API.

Les scopes de l'application ne remplacent pas les permissions normales de l'utilisateur. Même lorsqu'un scope est accordé, l'application ne peut travailler que sur les données accessibles à cet utilisateur.

La modification des URI de redirection ou des scopes crée une nouvelle version d'approbation. Les comptes déjà connectés doivent revoir et approuver la nouvelle version, et les utilisateurs doivent se reconnecter.

Connexion d'un compte client

Une application partenaire privée doit être approuvée explicitement par un administrateur dans chaque compte.

Ouvrez l'application dans votre compte partenaire.
Dans la zone du lien d'approbation, saisissez le nom du compte client.
Copiez le lien généré et envoyez-le à un administrateur de ce compte.
Demandez à l'administrateur de vérifier le propriétaire, les URI de redirection et les scopes, puis d'approuver l'application.
Après approbation, les utilisateurs du compte peuvent compléter l'autorisation OAuth. Chaque utilisateur consent séparément en son nom propre.

Le lien ouvre Gestion du compte → API → Applications OAuth et MCP et affiche l'application demandée.

Un administrateur qui connecte également l'application peut sélectionner Approuver et connecter.

Applications privées et publiées

Statut	Comment elle est admise dans un compte
Privée	Nécessite toujours une approbation explicite d'un administrateur de chaque compte.
Publiée	Disponible sans approbation séparée lorsque la politique du compte est Autoriser les applications publiées. Elle nécessite toujours une approbation lorsque la politique est Applications approuvées uniquement.

La publication fait l'objet d'un examen distinct par Planfix. Avant de soumettre une application, préparez un nom et une description clairs, un ensemble minimal de scopes, des URI de redirection fonctionnels et une documentation utilisateur pour la connexion et la suppression de l'intégration. Contactez le Support Planfix pour la procédure de publication.

Adresses de connexion

Utilisez les points de terminaison OAuth globaux :

Objet	Adresse
Autorisation	`https://auth.planfix.com/oauth/authorize`
Token	`https://auth.planfix.com/oauth/token`
Userinfo	`https://auth.planfix.com/oauth/userinfo`
MCP	`https://mcp.planfix.com/mcp`

N'ajoutez pas le nom du compte à une URL globale. L'utilisateur sélectionne le compte sur une page Planfix. Le protocole complet, y compris resource, PKCE, le rafraîchissement de token et la révocation, est décrit dans OAuth 2.0 pour les applications.

Gestion d'une application

Un partenaire peut :

modifier le nom et la description ;
changer les URI de redirection et les scopes ;
désactiver et réactiver l'application ;
faire pivoter le client secret d'une application confidentielle ;
générer un lien d'approbation d'application pour un compte spécifique.

Après la rotation du secret, l'ancien client secret cesse de fonctionner immédiatement. Mettez à jour le secret sur le serveur d'intégration et ne l'envoyez jamais aux utilisateurs.

La désactivation d'une application bloque l'autorisation OAuth et les tokens émis dans chaque compte. Cette action affecte tous les clients utilisant l'application.

Recommandations avant le lancement

Utilisez Authorization Code avec PKCE S256 et validez state.
Demandez uniquement les scopes dont vous avez besoin.
Affichez le compte sélectionné à l'utilisateur après la connexion.
Gérez la rotation des refresh tokens : après un rafraîchissement réussi, le refresh token précédent n'est plus valide.
N'écrivez pas de tokens, codes d'autorisation, code_verifier ou secrets clients dans les logs.
Documentez comment les utilisateurs peuvent déconnecter l'intégration et demander la suppression de leurs données.
Testez les scénarios de révocation d'approbation, de désactivation d'application et de reconnexion.