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

# Аутентификация MCP в Didit: вход через OAuth

> Аутентификация Didit MCP через OAuth 2.1 с PKCE: динамическая регистрация клиентов, области доступа, роли и подключение из любого клиента.

Didit MCP аутентифицируется с помощью функции **«Войти через Didit»** (OAuth 2.1). Он выступает в роли **пользователя** Didit с разрешениями вашей роли в консоли: **режима API-ключа не существует**.

***

## Вход через Didit

Размещённый сервер (`https://mcp.didit.me/mcp`) является **ресурсным сервером** OAuth 2.1. **Didit Business Console** (`business.didit.me`) выступает в роли **сервера авторизации**: он показывает экран согласия и выдаёт токены. Ваш MCP-клиент выполняет стандартный сценарий автоматически:

**1. Обнаружение**

Клиент отправляет запрос на `/mcp` без токена и получает `401` с заголовком `WWW-Authenticate: Bearer`, в котором `resource_metadata` указывает на метаданные защищённого ресурса (RFC 9728):

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

Этот документ описывает ресурс (`https://mcp.didit.me/mcp`), сервер авторизации (`https://business.didit.me`) и поддерживаемые области доступа. Тот же документ также доступен в корне исходного домена по адресу `https://mcp.didit.me/.well-known/oauth-protected-resource` для клиентов, которые сначала проверяют этот путь.

**2. Регистрация (динамическая регистрация клиента)**

Клиент читает метаданные сервера авторизации по адресу `https://business.didit.me/.well-known/oauth-authorization-server` и, если у него ещё нет client id, регистрирует себя на `registration_endpoint` (RFC 7591). С вашей стороны ничего заранее настраивать не нужно: локальные клиенты с loopback- или нативным URL обратного вызова (Claude Code, Cursor, MCP Inspector) и облачные клиенты с проверенным URL обратного вызова (Claude) регистрируются именно так. Удалённый URL обратного вызова, который Didit не проверял, отклоняется с ошибкой `invalid_redirect_uri`. Такой клиент сначала должен быть зарегистрирован оператором.

**3. Авторизация (PKCE)**

Клиент открывает `https://business.didit.me/authorize` с PKCE-челленджем S256. Вы входите в систему (или регистрируетесь) и видите, какие разрешения запрашиваются. Клиенты являются публичными: токен-эндпоинт не принимает client secret (`token_endpoint_auth_methods_supported` равен `none`), поэтому связь кода с клиентом обеспечивает именно PKCE.

**4. Согласие**

Вы подтверждаете доступ. Консоль создаёт сессию для этого приложения, привязанную к одобренным вами областям доступа, и возвращает код авторизации. Клиент обменивает его через `token_endpoint` на токен доступа и токен обновления.

**5. Вызов инструментов**

Клиент отправляет токен доступа с каждым запросом. MCP проверяет токен через интроспекцию по RFC 7662 в сервисе аутентификации Didit (токены непрозрачные, а не JWT), читает разрешения вашей организации из ответа интроспекции и действует от **вашего** имени на время этого запроса.

### Области доступа

Метаданные ресурса объявляют три области доступа. На экране согласия простым языком показано, какие из них запрашивает клиент:

| Область доступа | Предоставляет |
| - | - |
| `didit:management` | Управление вашим рабочим пространством: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` и `analytics`. |
| `didit:verification` | Запуск и проверка верификаций: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` и `analytics`. |
| `didit:staff` | Зарезервировано для учётных записей сотрудников Didit. Для обычной учётной записи не открывает ничего, а в сборке с открытым исходным кодом не определено ни одного инструмента только для сотрудников. |

Обе области доступа включают `analytics`. Управление `lists` требует `didit:management`, а доступ к `blocklist` требует `didit:verification`.

В [справочнике инструментов](https://docs.didit.me/ru/integration/mcp/tools.md) указано, к какой области доступа относится каждый инструмент. Одобренные вами области доступа передаются в токене и проверяются на стороне сервера. Поэтому приложение, подключённое только с `didit:verification`, получает отказ при обращении к интерфейсу управления, даже если ваша роль это позволяет. Сервер авторизации также знает области OpenID (`openid profile email`): подключение, которое запрашивает только их, может узнать, кто вы, и больше ничего.

Эффективные разрешения приложения представляют собой **пересечение** одобренных областей доступа и вашей роли в консоли, но никогда не превышают более узкое из двух.

Чтобы создать сессию верификации с помощью `didit_session_create`, нужны область доступа `didit:verification` **и** роль с `create:sessions` или `write:sessions`. Роль **Developer** включает `create:sessions`. Одобрение только `didit:management` не позволяет создавать сессии, даже если ваша роль содержит нужное разрешение.

### Роли и разрешения

Токен представляет **вас**, поэтому агент может работать во **всех организациях, в которых вы состоите**, в рамках одного подключения. Инструменты, работающие между приложениями (`didit_session_search`, `didit_analytics`, `didit_context_get` и остальные инструменты `*_search`), автоматически агрегируют данные по всем этим организациям.

Ваша **роль всегда проверяется** бэкендом Didit отдельно для каждой организации. Каждый инструмент соответствует одному идентификатору разрешения бэкенда (например, `write:sessions` для `didit_session_update_status` и `delete:sessions` для `didit_session_delete`). В [справочнике инструментов](https://docs.didit.me/ru/integration/mcp/tools.md) это указано для каждого инструмента. Сервер также проверяет это разрешение до отправки запроса, используя разрешения, которые ответ интроспекции содержит для вашей организации:

* В режиме `enforce` инструмент, который ваша роль не может выполнить, не включается в `tools/list`. Если всё же вызвать его, возвращается ошибка `missing_scope`, которая называет разрешение: `"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`
* В режиме `shadow` (режим сервера по умолчанию) все инструменты показываются в списке, а вызов передаётся бэкенду. Бэкенд отвечает `403`, если роль не имеет разрешения. Решение лишь записывается в журнал аудита сервера.

В любом случае MCP никогда не предоставляет больше, чем уже разрешает ваша роль в консоли. `READER` может просматривать и читать, а `OWNER` или `ADMIN` могут записывать и удалять.

### Время жизни токена

Одобренное приложение получает собственную сессию, отдельную от браузерной сессии, из которой вы его одобрили. Токены доступа имеют короткий срок действия. Клиент автоматически обновляет их с помощью токена обновления (`grant_types_supported` включает `refresh_token`). Обновление сохраняет области доступа приложения и остаётся привязанным к этому приложению. Если обновление не удалось (например, после того как вы отключили приложение), клиент при следующем вызове заново запускает **Вход через Didit**.

Выход из консоли не завершает сессии в подключённых приложениях, а отключение приложения никогда не выполняет выход из системы нигде.

### Отключение приложения

**1. Из консоли**

В разделе **Settings → Authentication → Connected apps** показано каждое приложение, которое вы одобрили, с его зарегистрированным названием и выданными разрешениями. **Отключить** немедленно прекращает доступ этого приложения: и его токен доступа, и его refresh-токен перестают работать, а остальное не затрагивается.

**2. Из приложения (RFC 7009)**

Клиент может отозвать собственный доступ, отправив токен на `revocation_endpoint` сервера авторизации, который указан в метаданных по адресу `https://business.didit.me/.well-known/oauth-authorization-server`. Как требует RFC 7009, успешный вызов возвращает `200` независимо от того, был ли токен ещё действительным, поэтому ответ никогда не сообщает, был ли токен действительным. Ответ `503` означает, что отозвать токен не удалось: считайте токен всё ещё действительным и повторите запрос.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **Почему без API-ключа?** Каждый MCP-инструмент обращается к эндпоинтам консоли, доступным в контексте пользователя (`/organization/{org}/application/{app}/…`), которые авторизуют Bearer-токен с привилегиями, зависящими от роли, и **отклоняют `x-api-key`**. API-ключ приложения предназначен для прямых вызовов [REST API](https://docs.didit.me/openapi-25.json) из вашего собственного бэкенда (например, для создания сессий), а не для этого MCP. `didit_org_list_api_keys` показывает метаданные ключей со скрытыми значениями; инструмент, который раскрывает сам ключ, на размещённом коннекторе скрыт.

***

## Подключение с каждого клиента

Все клиенты используют один и тот же процесс; различается только способ передачи им URL.

> [tab] Claude
>
> Используйте глубокую ссылку, которую Business Console показывает на странице интеграции. Она открывает claude.ai с предзаполненным диалогом **Add custom connector**:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Подтвердите, затем выполните **Вход через Didit**. Claude Desktop использует тот же URL в **Settings → Connectors → Add custom connector**. Подробности в разделе [Connect Claude](https://docs.didit.me/ru/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Затем выполните `/mcp` внутри Claude Code, чтобы запустить вход через браузер.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursor регистрируется сам и открывает браузер при первом использовании.

> [tab] Универсальный клиент
>
> Направьте любой клиент Streamable HTTP с поддержкой OAuth 2.1 на `https://mcp.didit.me/mcp`. Он должен:
>
> 1. Выполнить `POST /mcp`, получить `401` и прочитать `resource_metadata` из `WWW-Authenticate`.
> 2. Запросить `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp`, затем метаданные сервера авторизации по адресу `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. Зарегистрироваться на `registration_endpoint`, если у него нет идентификатора клиента.
> 4. Выполнить поток авторизации по коду с PKCE (S256) на `authorization_endpoint`, затем обменять код на токен в `token_endpoint`.
> 5. Отправлять `Authorization: Bearer <access_token>` с каждым запросом `POST /mcp`.
>
> Клиенты без поддержки OAuth могут работать через `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, который выполняет за них шаги 1–5.

***

## Ошибки аутентификации

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

Ответ `401` от `/mcp` означает, что токен отсутствует, истёк или был отозван: клиенту следует обновить токен или заново выполнить **Вход через Didit**.

Ответ `403` или ошибка `missing_scope` для *конкретного* инструмента обычно означает одно из двух: ваша **роль** не имеет нужного разрешения (например, `READER` пытается выполнить запись), либо подключение было одобрено без области действия, которая нужна этому инструменту. Это не означает, что всё подключение неисправно. Повторное подключение с одобрением обеих областей действия исправляет второй случай; первый требует смены роли.

Если не работает ни один инструмент, проверьте **Settings → Authentication → Connected apps** в консоли: приложение, которое там было отключено, нужно одобрить заново.

***

> [card] [Справочник инструментов](https://docs.didit.me/ru/integration/mcp/tools.md)
>
> Что делает каждый инструмент, его scope и разрешение роли.

> [card] [Расширенные возможности](https://docs.didit.me/ru/integration/mcp/advanced.md)
>
> Роли, поведение между приложениями и самостоятельное развёртывание.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.