> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chataigne.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentification et permissions MCP

> Comprenez les scopes OAuth, rôles en temps réel, memberships et accès administrateur global du MCP Chataigne.

Chaque requête vers `POST /mcp` exige un access token OAuth émis pour l’audience exacte de la ressource MCP. Chataigne vérifie le token, la session utilisateur active, le client OAuth, le consentement et les scopes à chaque requête.

## Autorisation effective

Un outil métier est autorisé par l’intersection de trois contrôles :

```text theme={null}
scopes OAuth consentis
  ∩ permissions actuelles du rôle
  ∩ membership actuel de la ressource cible
```

Le serveur résout en base de données la véritable organisation propriétaire de la cible. Un appelant ne peut pas autoriser un article de catalogue, une commande ou une conversation en fournissant l’identifiant d’un autre établissement.

| Appelant                                       | Règle multi-tenant                                                                                   | Règle de scope |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------- |
| Utilisateur restaurant                         | Exige un membership actuel dans l’établissement ou son organisation parente et la permission de rôle | Toujours exigé |
| Administrateur global Chataigne                | Peut cibler toute organisation ou établissement sans membership                                      | Toujours exigé |
| Utilisateur révoqué ou banni                   | Refusé à la requête suivante                                                                         | Non applicable |
| Client OAuth désactivé ou consentement révoqué | Refusé à la requête suivante                                                                         | Non applicable |

<Warning>
  L’accès administrateur global est large mais jamais implicite. Le token doit contenir le scope de
  lecture ou d’écriture requis. N’accordez les scopes d’écriture en production qu’aux clients de
  confiance.
</Warning>

## Scopes

Les scopes d’identité sont `openid`, `profile` et `offline_access`. Les scopes métier suivent le format `ressource.action`.

| Domaine                  | Scopes de lecture                                                                                                                               | Scopes d’écriture              |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| Espaces de travail       | `businessOrganization.read`, `location.read`                                                                                                    | —                              |
| Paramètres établissement | `storeSettings.read`, `orderSettings.read`, `openingHoursSettings.read`, `deliverySettings.read`, `paymentMethodSettings.read`, `settings.read` | —                              |
| Statut des commandes     | `locationStatusSettings.read`                                                                                                                   | `locationStatusSettings.write` |
| Catalogue                | `catalog.read`                                                                                                                                  | `catalog.updateAvailability`   |
| Commandes                | `orders.read`                                                                                                                                   | `orders.write`                 |
| Clients                  | `customers.read`                                                                                                                                | —                              |
| Conversations            | `conversations.read`                                                                                                                            | `conversations.write`          |
| Analytics                | `analytics.read`                                                                                                                                | —                              |
| Remises                  | `discounts.read`                                                                                                                                | —                              |
| Intégrations             | `integrations.read`                                                                                                                             | —                              |
| Autres paramètres        | `ai.read`, `loyalty.read`, `referrals.read`, `notifications.read`                                                                               | —                              |

Les outils dont le scope statique est absent n’apparaissent pas dans `tools/list`. Appeler directement un outil masqué ne contourne pas ce contrôle. `chataigne_location_settings_get` vérifie aussi le scope granulaire de chaque section demandée et refuse l’appel entier si une section n’est pas autorisée. Les scopes d’administration de plateforme et leurs contrôles supplémentaires de rôle en temps réel sont documentés uniquement dans l’espace Admin protégé.

## Cycle de vie du token

* Les access tokens sont liés à l’audience de l’URL MCP canonique.
* Authorization Code utilise PKCE.
* Les refresh tokens tournent.
* Une session Better Auth actuelle, un utilisateur actif, un client OAuth activé et un consentement correspondant sont exigés.
* Les memberships et permissions de rôle sont lus en temps réel : une suppression d’accès prend effet à la requête MCP suivante.

## Scopes recommandés

Pour un assistant limité aux questions opérationnelles, commencez avec :

```text theme={null}
openid profile offline_access
location.read catalog.read orders.read
customers.read conversations.read analytics.read
```

Ajoutez chaque scope d’écriture uniquement si le client est fiable et l’action opérationnelle nécessaire. Les outils d’écriture peuvent aussi être désactivés globalement, indépendamment du consentement OAuth.

## Échecs d’authentification

Les échecs d’authentification renvoient HTTP `401` avec un header `WWW-Authenticate` vers les métadonnées de la ressource protégée. Les refus de permission d’un outil renvoient une erreur MCP sûre `MCP_RESOURCE_FORBIDDEN` sans révéler si un identifiant appartenant à un autre tenant existe.