OAuth 2.0 pour les applications

OAuth 2.0 permet à une application d'accéder à Planfix au nom d'un utilisateur sans demander ni stocker le mot de passe de l'utilisateur.

Planfix utilise le flux Authorization Code avec PKCE S256 obligatoire. OAuth peut être utilisé pour se connecter au REST API ou au Planfix MCP server.

Si vous souhaitez connecter un client IA prêt à l'emploi, commencez par Planfix MCP. Si vous gérez l'accès dans votre compte, voir OAuth and MCP applications in an account. Les partenaires et développeurs d'intégrations multi-comptes doivent consulter OAuth applications for partners.

Options d'enregistrement d'application

Option	Quand l'utiliser	Où ça fonctionne
Application appartenant au compte	L'intégration est destinée à un seul compte et le client a besoin d'un client_id prédéfini.	Uniquement dans le compte qui en est le propriétaire.
Application appartenant au partenaire	La même application doit se connecter à plusieurs comptes clients.	Dans les comptes où cela est autorisé par la politique de sécurité ou par un administrateur.
Enregistrement automatique du client MCP	Le client MCP prend en charge un Client ID Metadata Document (CIMD) ou Dynamic Client Registration (DCR).	L'enregistrement n'accorde pas l'accès au compte en soi. L'application doit encore être autorisée dans le compte sélectionné.

CIMD et DCR sont disponibles uniquement pour les connexions MCP. Pour la REST API, utilisez une application appartenant au compte ou au partenaire.

Endpoints OAuth

Les nouvelles intégrations doivent utiliser les endpoints globaux. Le nom du compte n'est pas inclus dans ces URLs : l'utilisateur sélectionne un compte lors de l'autorisation.

Objet	Adresse
Issuer	https://auth.planfix.com
Authorization	https://auth.planfix.com/oauth/authorize
Token	https://auth.planfix.com/oauth/token
User information	https://auth.planfix.com/oauth/userinfo
Token revocation	https://auth.planfix.com/oauth/revoke
Dynamic MCP client registration	https://auth.planfix.com/oauth/register

Les métadonnées du serveur d'autorisation sont disponibles aux endpoints standards :

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

Redirect URIs

Une redirect URI doit être enregistrée dans les paramètres de l'application. La valeur envoyée dans une requête d'autorisation doit correspondre à une URI enregistrée.

Sont autorisées :

• les URLs https ;
• les URLs http uniquement pour les hôtes loopback, tels que localhost ou 127.0.0.1.

Le port peut être dynamique pour une URI loopback, mais son schéma, hôte, chemin et query doivent correspondre. Les fragments d'URL et les informations utilisateur dans l'URL ne sont pas autorisés.

Niveaux d'accès

Une application reçoit uniquement les niveaux d'accès, ou scopes, qui ont été autorisés à l'avance. Voir REST API access levels pour la liste complète.

L'ensemble demandé doit être un sous-ensemble des scopes enregistrés pour l'application. Les scopes de l'application n'étendent pas les permissions de l'utilisateur dans Planfix : l'application ne peut accéder qu'aux données disponibles pour l'Employé qui l'a connectée.

Les applications gérées reçoivent également les scopes de service userinfo, openid et email.

Autorisation de l'utilisateur

Générez un code_verifier et sa représentation SHA-256, code_challenge, puis ouvrez l'endpoint d'autorisation dans un navigateur.

Exemple 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

Pour MCP, ajoutez le paramètre resource avec l'URL exacte du serveur MCP :

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

Paramètre	Description
client_id	L'identifiant d'une application enregistrée. Pour CIMD, c'est l'URL du document de métadonnées du client.
redirect_uri	Une des redirect URIs autorisées.
response_type	Doit être code.
scope	Les permissions requises séparées par des espaces. Ce paramètre est obligatoire pour la REST API. Un client MCP peut l'omettre, auquel cas les scopes autorisés pour l'application sont utilisés.
state	Une valeur aléatoire qui protège la requête contre la substitution. L'application doit la valider après la redirection.
code_challenge	Base64url sans padding du hash SHA-256 de code_verifier.
code_challenge_method	Seul S256 est pris en charge.
resource	Pour MCP, l'URL exacte https://mcp.planfix.com/mcp. N'envoyez pas ce paramètre pour la REST API.

L'utilisateur sélectionne un compte, se connecte et examine les permissions demandées. Une application appartenant au compte ouvre directement le compte propriétaire. Si la politique de sécurité nécessite l'approbation d'un administrateur, Planfix affiche l'étape correspondante. Un administrateur peut approuver l'application et la connecter en une seule action.

Après une autorisation réussie, Planfix redirige le navigateur vers redirect_uri :

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Un code d'autorisation est à usage unique et reste valide pendant 10 minutes.

Obtention des tokens

Envoyez une requête POST vers /oauth/token en utilisant 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

Pour MCP, répétez le paramètre resource avec la même valeur utilisée dans la requête d'autorisation.

Un client public envoie la requête sans secret. Un client confidentiel s'authentifie également en utilisant client_secret_basic ou les paramètres client_id et client_secret dans le corps de la requête.

Exemple de réponse :

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Pour la REST API, la réponse contient également account_name, account_domain et account_url. Stockez ces valeurs et utilisez l'URL du compte sélectionné pour les requêtes REST API.

Un access token est valable 24 heures. Il est lié à l'utilisateur, au compte, à l'application, aux scopes et à la ressource. Un token émis pour MCP ne peut pas être utilisé directement avec la REST API, et un token REST API ne peut pas être utilisé avec MCP.

Utiliser un token avec la REST API

Envoyez le token dans l'en-tête Authorization :

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Utilisez l'URL du compte renvoyée lorsque le code d'autorisation a été échangé contre des tokens. Seules les méthodes couvertes par les scopes accordés sont disponibles. Les tokens OAuth sont soumis au plan du compte et aux REST API limits standard.

Informations sur l'utilisateur

La requête userinfo nécessite le scope openid :

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Exemple de réponse lorsque le scope email est présent :

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

L'autorisation OAuth globale est disponible pour les Employés du compte. Planfix n'émet pas d'id_token ; demandez plutôt les données utilisateur via userinfo.

Actualisation des tokens

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

Pour MCP, envoyez à nouveau le même resource. Un client confidentiel doit s'authentifier en utilisant son secret.

Planfix renvoie un nouvel access token et un nouveau refresh token. Le refresh token précédent devient invalide immédiatement, donc l'application doit remplacer la valeur stockée de manière atomique.

Révocation d'un token

Un client peut révoquer un refresh token via /oauth/revoke :

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Un utilisateur peut aussi supprimer une connexion depuis la section Session management de sa fiche utilisateur. Un administrateur peut révoquer l'approbation d'une application tierce pour l'ensemble du compte. Voir OAuth and MCP applications in an account.

Compatibilité avec les intégrations existantes

Les endpoints de tenant tels que https://account.planfix.com/api/v2/oauth/authorize, /token, et /userinfo continuent de fonctionner pour les intégrations existantes liées à un compte spécifique.

Utilisez les endpoints globaux pour les nouvelles intégrations. Ils prennent en charge la découverte de métadonnées standard, la sélection de compte et MCP. Ne pas mélanger les endpoints globaux et de tenant dans une même session OAuth.

Recommandations de sécurité

• Utilisez toujours PKCE S256 et validez le state.
• Utilisez un client public sans secret pour les applications mobiles, desktop et web.
• N'utilisez un client confidentiel que lorsque le secret peut être stocké de manière sécurisée sur un serveur.
• Demandez l'ensemble minimal de scopes requis.
• N'écrivez pas les access tokens, refresh tokens, codes d'autorisation, code_verifier ou secrets client dans les logs.
• Stockez les refresh tokens et secrets client dans un stockage chiffré.
• Validez le iss dans la réponse et n'acceptez que l'issuer Planfix attendu.

Erreurs possibles

Erreur	Cause
invalid_client	Le client est inconnu ou désactivé, le client secret est incorrect, ou l'application n'est pas disponible dans le compte sélectionné.
invalid_grant	Le code d'autorisation ou le refresh token est invalide, expiré, déjà utilisé, ou ne correspond pas au client, à la redirect URI, aux données PKCE ou à la ressource.
invalid_scope	La requête contient un scope qui n'est pas autorisé pour l'application.
invalid_target	Le resource n'est pas pris en charge ou a changé entre les requêtes.
access_denied	L'utilisateur a refusé la connexion ou la politique du compte n'autorise pas l'application.
HTTP 401, invalid_token	Le access token est inconnu, expiré ou révoqué.
HTTP 403, insufficient_scope	Le token ne contient pas le scope requis pour l'opération.

Go To

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