> ## 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.

# MCP authentication and permissions

> Understand OAuth scopes, live roles, tenant membership, and global administrator access for Chataigne MCP.

Every request to `POST /mcp` requires an OAuth access token issued for the exact MCP resource audience. Chataigne verifies the token, active user session, OAuth client, consent and scopes on every request.

## Effective authorization

A business tool is authorized by the intersection of three controls:

```text theme={null}
consented OAuth scopes
  ∩ current role permissions
  ∩ current membership of the target resource
```

The server resolves the target's real owning organization from the database. A caller cannot authorize a catalog item, order or conversation by supplying an unrelated location identifier.

| Caller                                   | Tenant rule                                                                                                 | Scope rule      |
| ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------- |
| Merchant user                            | Requires a live membership in the location or parent business organization and the required role permission | Always required |
| Global Chataigne administrator           | May address every organization and location without membership                                              | Always required |
| Revoked or banned user                   | Denied on the next request                                                                                  | Not applicable  |
| Disabled OAuth client or revoked consent | Denied on the next request                                                                                  | Not applicable  |

<Warning>
  Global administrator access is broad but never implicit. The token must contain the required read
  or write scope. Grant production write scopes only to trusted clients.
</Warning>

## Scopes

Identity scopes are `openid`, `profile`, and `offline_access`. Business scopes follow the permission identifier format `resource.action`.

| Domain                       | Read scopes                                                                                                                                     | Write scopes                   |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| Workspaces                   | `businessOrganization.read`, `location.read`                                                                                                    | —                              |
| Location settings            | `storeSettings.read`, `orderSettings.read`, `openingHoursSettings.read`, `deliverySettings.read`, `paymentMethodSettings.read`, `settings.read` | —                              |
| Ordering status              | `locationStatusSettings.read`                                                                                                                   | `locationStatusSettings.write` |
| Catalog                      | `catalog.read`                                                                                                                                  | `catalog.updateAvailability`   |
| Orders                       | `orders.read`                                                                                                                                   | `orders.write`                 |
| Customers                    | `customers.read`                                                                                                                                | —                              |
| Conversations                | `conversations.read`                                                                                                                            | `conversations.write`          |
| Analytics                    | `analytics.read`                                                                                                                                | —                              |
| Discounts                    | `discounts.read`                                                                                                                                | —                              |
| Integrations                 | `integrations.read`                                                                                                                             | —                              |
| Additional settings sections | `ai.read`, `loyalty.read`, `referrals.read`, `notifications.read`                                                                               | —                              |

Tools whose static scope is absent do not appear in `tools/list`. Calling a hidden tool directly does not bypass the check. `chataigne_location_settings_get` additionally checks the granular scope for every requested section and fails the whole call if one section is not authorized. Platform-administration scopes and their additional live-role checks are documented only in the gated Admin section.

## Token lifecycle

* Access tokens are audience-bound to the canonical MCP URL.
* Authorization Code uses PKCE.
* Refresh tokens rotate.
* A current Better Auth session, active user, enabled OAuth client and matching consent are required.
* Memberships and role permissions are read live, so access removal takes effect on the next MCP request.

## Recommended grants

For an assistant that only answers operational questions, start with:

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

Add each write scope only when the client is trusted and the operational action is required. Write tools can also be disabled platform-wide independently of OAuth consent.

## Authentication failures

Authentication failures return HTTP `401` and a `WWW-Authenticate` header pointing to protected-resource metadata. Tool-level permission failures return a safe MCP error with code `MCP_RESOURCE_FORBIDDEN`; the message does not reveal whether a cross-tenant identifier exists.