--- title: "Scopes OAuth" description: "Comprendre les scopes disponibles, comment l'accès est contrôlé, et comment demander les bonnes permissions pour votre intégration." canonical: https://developer.billabex.com/fr/guides/scopes/ lang: fr alternate: https://developer.billabex.com/en/guides/scopes/ last-updated: 2026-10-03 --- # Scopes OAuth > Comprendre les scopes disponibles, comment l'accès est contrôlé, et comment demander les bonnes permissions pour votre intégration. Source: https://developer.billabex.com/fr/guides/scopes/ Langue: Français (fr) Version anglaise: https://developer.billabex.com/en/guides/scopes/ 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. | Scope | Rôle | | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `openid` | Active OIDC et l'émission du jeton d'identité | | `profile` | Ajoute les claims de profil, et gère l'avatar et les [préférences de notification](/fr/guides/preferences-de-notification/) de l'utilisateur courant | | `email` | Ajoute les claims d'email (`email`, `email_verified`) | ### Facturation | Scope | Niveau d'accès | Endpoints représentatifs | | ------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invoices:read` | Lecture seule | | | `invoices:all` | Accès complet | | | `credit-notes:read` | Lecture seule | | | `credit-notes:all` | Accès complet | | | `accounts:read` | Lecture seule | | | `accounts:all` | Accès complet | | ### Suivi des paiements et communications | Scope | Niveau d'accès | Endpoints représentatifs | | --------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `communications:read` | Lecture seule | | | `dunning:manage` | Accès complet | | ### 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. | Scope | Niveau d'accès | Endpoints représentatifs | | ------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tasks:read` | Lecture seule | | | `tasks:all` | Accès complet | | ### Plateforme | Scope | Niveau d'accès | Endpoints représentatifs | | -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `organizations:read` | Lecture seule | | | `organizations:all` | Accès complet | | ### MCP (Model Context Protocol) Ces scopes sont utilisés par les clients MCP qui se connectent au serveur MCP Billabex. | Scope | Niveau d'accès | Description | | ----------- | -------------- | ------------------------------------------------------------------- | | `mcp:read` | Lecture seule | Autorise les outils MCP à lire factures, comptes et communications. | | `mcp:write` | Écriture | Autorise les outils MCP à créer, modifier et supprimer des données. | Voyez **[Serveur MCP](/fr/guides/mcp/)** pour la liste complète des outils et des ressources. ### Nature des écritures | Scope | Niveau d'accès | Description | | ------ | -------------- | -------------------------------------------------------------------------------- | | `sync` | Aucun | Déclare ce client comme une synchronisation automatisée. N'ouvre aucun endpoint. | `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. ```text openid email accounts:all invoices:all sync ``` ## Demander des scopes Incluez-les dans la requête d'autorisation OAuth : ```javascript const authUrl = new URL('https://next.billabex.com/api/oauth/authorize'); authUrl.searchParams.append( 'scope', 'openid email invoices:read accounts:read', ); ``` ## Ensembles recommandés ### Reporting en lecture seule ```text openid email invoices:read credit-notes:read accounts:read ``` ### Gestion des factures ```text openid email invoices:all credit-notes:all accounts:read ``` ### Assistant de suivi des paiements ```text openid email invoices:read accounts:read communications:read dunning:manage ``` ### Outil d'administration d'organisation ```text openid email organizations:all ``` ### Gestion des tâches de compte ```text openid email tasks:all accounts:read ``` ### Client MCP ```text mcp:read mcp:write ``` Voyez **[Serveur MCP](/fr/guides/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é. ```json { "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. ```json { "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](/fr/guides/demarrage/)** : le parcours d'intégration rapide - **[Authentification OAuth](/fr/guides/oauth/)** : le guide complet OAuth 2.1 et PKCE - **[Référence de l'API](/fr/reference-api/)** : le détail endpoint par endpoint ## Support Une question sur les scopes et les permissions ? Écrivez-nous via le [formulaire de contact](https://www.billabex.com/fr/contactez-nous/). ## Préférence de relance par client `PUT /api/public/v1/accounts/:accountId/dunning/preferences` accepte `{ "preventPreDueReminders": true }` avec le scope `dunning:manage`. Le MCP propose `set-account-dunning-preferences` avec les paramètres `accountId` et `preventPreDueReminders`, sous `mcp:write`. Le réglage est permanent et désactivé par défaut. Il exclut des relances automatiques les factures non échues et les montants d’échéancier non encore exigibles. Le jour de l’échéance est inclus ; les délais plus longs de l’organisation restent applicables. Envoyer `false` rétablit le comportement de l’organisation sans lever une suspension. Le statut renvoie `preventPreDueReminders`, `invoiceDueEligibleAt` et, pendant cette attente, `silenceReason: "invoice-due-date-pending"`. La date est une réévaluation, pas une promesse d’envoi. --- Billabex developer portal. OpenAPI specification: https://developer.billabex.com/openapi.json. Agent instructions: https://developer.billabex.com/llms.txt. Complete documentation: https://developer.billabex.com/llms-full.txt.