Scopes OAuth

Les scopes OAuth définissent ce que votre application a le droit de faire une fois l’accès accordé par un utilisateur. Ce guide explique comment Billabex les contrôle et comment choisir le bon ensemble.

Vue d’ensemble

Sur le principe :

1. votre application demande des scopes à l’étape d’autorisation OAuth ;
2. l’utilisateur approuve ces permissions ;
3. Billabex émet des jetons qui portent les scopes accordés ;
4. chaque endpoint vérifie les scopes avant d’exécuter la requête.

Notions clés

• Séparés par des espaces : les scopes se demandent sous forme d’une chaîne séparée par des espaces.
• Moindre privilège : ne demandez que ce dont votre intégration a besoin.
• Lecture ou écriture : la plupart des scopes de ressource suivent le motif :read (lecture seule) et :all (lecture et écriture).
• Logique OU : si un endpoint accepte plusieurs scopes, en détenir un suffit.
• Pas d’élévation sur un jeton existant : pour ajouter des permissions, il faut refaire le parcours OAuth en demandant des scopes plus larges.

Les scopes disponibles

OpenID Connect (OIDC)

À utiliser quand vous avez besoin des claims d’identité de l’utilisateur.

Facturation

Suivi des paiements et communications

Tâches de compte

Les tâches de compte sont ouvertes par l’agent Billabex quand il a besoin d’une intervention humaine. Ces scopes contrôlent l’accès à leurs endpoints.

Plateforme

MCP (Model Context Protocol)

Ces scopes sont utilisés par les clients MCP qui se connectent au serveur MCP Billabex.

Voyez Serveur MCP pour la liste complète des outils et des ressources.

Nature des écritures

sync est le seul scope qui n’ouvre rien. Il indique à Billabex que les écritures venant de ce client sont des écritures machine et non celles d’une personne, ce qui change la façon dont les données de contact sont fusionnées :

• Le fullName et la language d’un contact restent à qui les a saisis. Si une personne a renseigné l’un de ces champs depuis la webapp ou par un client sans sync, un client sync ne peut plus l’écraser. Il peut toujours renseigner un champ que personne n’a saisi.
• Les numéros de téléphone sont rangés à part. Chaque numéro porte une origin : Manual pour un numéro saisi par une personne, Connector pour un numéro écrit par une synchronisation, ce qui inclut la vôtre dès que vous détenez sync. Écrire phones ne remplace que votre propre pile et laisse l’autre intacte : une synchronisation et l’équipe du client cessent donc de s’effacer mutuellement.
• Un numéro illisible est ignoré plutôt que de faire échouer la requête. Un numéro impossible à normaliser (pas de countryCode sur un numéro national, du texte libre comme "voir Jean") est écarté et signalé, au lieu de transformer toute la mise à jour en 400. Sans sync, cela reste un 400, parce qu’il faut dire à une personne que sa saisie est erronée.

Ce qui est refusé ou écarté revient dans un tableau warnings sur la réponse du contact, chaque entrée nommant le field, la value ignorée et une reason valant MANUALLY_SET ou UNPARSEABLE. La clé est absente quand il n’y a rien à signaler. Lisez-la : sans elle, une écriture refusée est indiscernable d’une écriture qui n’a rien changé, les deux répondant 200 avec le contact tel qu’il est.

Comme sync ne fait que retirer des droits, il est auto-déclaré : demandez-le comme n’importe quel autre scope, sans étape d’approbation supplémentaire. Ne le demandez pas pour une intégration qu’une personne pilote à la main, sinon ses modifications seront classées comme des écritures machine.

openid email accounts:all invoices:all sync

Demander des scopes

Incluez-les dans la requête d’autorisation OAuth :

const authUrl = new URL('[baseURL]/api/oauth/authorize');
authUrl.searchParams.append(
  'scope',
  'openid email invoices:read accounts:read',
);

Ensembles recommandés

Reporting en lecture seule

openid email invoices:read credit-notes:read accounts:read

Gestion des factures

openid email invoices:all credit-notes:all accounts:read

Assistant de suivi des paiements

openid email invoices:read accounts:read communications:read dunning:manage

Outil d’administration d’organisation

openid email organizations:all

Gestion des tâches de compte

openid email tasks:all accounts:read

Client MCP

mcp:read mcp:write

Voyez Serveur MCP pour les outils et ressources disponibles.

Comportement de l’autorisation

Logique OU sur les endpoints

Quand un endpoint accepte plusieurs scopes, en détenir un seul suffit.

Par exemple :

• l’endpoint accepte invoices:read ou invoices:all ;
• un jeton ne portant que invoices:read est autorisé.

Sur-ensemble

Si vous détenez déjà ressource:all, vous n’avez pas besoin de ressource:read en plus pour la même ressource.

Erreurs courantes

invalid_scope

Se produit quand un scope demandé est inconnu ou mal formé.

{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid or unknown"
}

insufficient_scope

Se produit quand votre jeton ne porte pas un scope exigé par l’endpoint.

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "insufficient_scope"
}

Bonnes pratiques

• Demandez le jeu de scopes minimal nécessaire à votre intégration.
• Commencez par les scopes de lecture, et n’élargissez qu’en cas de besoin.
• Faites réautoriser vos utilisateurs quand votre application demande de nouvelles permissions.
• Réexaminez régulièrement les scopes demandés, à mesure que vos fonctionnalités évoluent.

Pour aller plus loin

• Démarrage : le parcours d’intégration rapide
• Authentification OAuth : le guide complet OAuth 2.1 et PKCE
• Référence de l’API : le détail endpoint par endpoint

Support

Une question sur les scopes et les permissions ? Écrivez-nous via le formulaire de contact.