Управление доступом

Powerduck разделяет доступ читателей к документации и клиентов к endpoint MCP, поскольку эти сервисы используются по-разному. Отдельно настраивается аутентификация сервера MCP в целевом API.

Последовательность проверок

Доступность публичного сервиса зависит от нескольких условий. Их проверка помогает понять, почему документ не открывается.

1. Состояние документа — требуется ACTIVE; документ не должен быть приостановлен, архивирован или удалён;
2. Сервис включён — documentationEnabled для документации, mcpEnabled для MCP;
3. Учётные данные доступа — пароль просмотра документации или ключ доступа MCP, если они настроены;
4. Срок действия — доступ к документации может быть ограничен по времени.

Публикуемые материалы автоматически собираются после добавления версии или изменения набора доступных операций. Обычно отдельная ручная публикация не требуется.

Сервисы независимы: отключение MCP не влияет на документацию, а пароль документации не ограничивает доступ к MCP.

Пароль просмотра документации

Пароль защищает и отображаемую документацию, и выдаваемые данные спецификации:

• Пароль хешируется с помощью scrypt с индивидуальной случайной солью; открытый текст не сохраняется;
• Если пароль установлен, читатель должен указать его до получения документа;
• Пароль защищает только документацию: endpoint MCP использует собственный ключ и не проверяет пароль просмотра.

Можно также задать срок доступа. После его окончания доступ запрещается даже с правильным паролем. Чтобы снять соответствующее ограничение, удалите пароль или срок действия.

Ключ доступа MCP

Endpoint MCP защищается собственным ключом доступа:

• Создайте или замените ключ: полный ключ возвращается один раз, далее отображаются только последние четыре символа;
• Если ключ настроен, каждый запрос MCP должен передавать его как токен Bearer;
• Ключ сравнивается за постоянное время. Отсутствующий или неверный ключ приводит к ответу 401.

Удаление ключа открывает доступ к endpoint MCP без него, если документ активен и MCP включён.

Аутентификация MCP в целевом API

Независимо от защиты endpoint можно настроить, как сервер MCP проходит аутентификацию в целевом API, описанном в спецификации. Поддерживаются следующие типы:

authType	Настройка
NONE	Без аутентификации в целевом API
BEARER	Bearer-токен
BASIC	Имя пользователя и пароль для базовой аутентификации
APIKEY	Имя и значение API-ключа в заголовке или параметре запроса

Секреты — bearer-токены, пароли и значения API-ключей — можно записывать, но нельзя прочитать обратно. В конфигурации указывается только факт их наличия.

Дополнительные настройки MCP:

• Замена базового URL — использование другого адреса целевого API вместо указанного в спецификации;
• Тайм-аут запроса — время ожидания при обращении сервера MCP к целевому API.

Рекомендуемая настройка

• Публичная документация: включите её без пароля для открытых API либо задайте пароль и срок действия для ограниченного доступа;
• MCP для своих агентов: включите MCP и создайте ключ, чтобы обращаться к нему могли только ваши клиенты;
• Аутентификация в API: настройте сервер MCP в соответствии с требованиями реального API, отдельно от правил доступа к самому endpoint MCP.

См. также: Публикуемые операции, Документы и версии, Собственные домены.