OAuth-приложения для партнеров

Материал из Planfix

Партнерское OAuth-приложение подходит для интеграции, которую нужно подключать к разным аккаунтам ПланФикса. Одни учетные данные приложения используются для всех клиентских аккаунтов, а каждый аккаунт отдельно управляет допуском и каждый пользователь отдельно подтверждает свои права.

Если интеграция нужна только одному аккаунту, проще создать приложение аккаунта.

Создание приложения

  1. Откройте свой партнерский кабинет.
  2. Перейдите в раздел OAuth-приложения.
  3. Нажмите Создать приложение.
  4. Укажите название и описание, которые увидят пользователи и администраторы.
  5. Выберите тип OAuth-клиента.
  6. Добавьте Redirect URI.
  7. Выберите минимально необходимые scope REST API.
  8. Сохраните приложение и скопируйте учетные данные.

После создания приложение является приватным и требует явного разрешения в каждом подключаемом аккаунте.

Тип OAuth-клиента

Тип Для каких приложений Учетные данные
Публичный Мобильные, настольные и браузерные приложения, локальные MCP-клиенты. Только client_id. Client secret отсутствует; обязателен PKCE S256.
Конфиденциальный Серверные приложения, где секрет можно хранить вне пользовательского устройства и клиентского кода. client_id и client_secret.

Публичность OAuth-клиента не связана с публикацией приложения в каталоге. Например, приватное мобильное приложение будет публичным OAuth-клиентом без секрета.

Redirect URI

Укажите все адреса, на которые ПланФикс может вернуть пользователя после входа.

  • Для веб-сервиса используйте https.
  • http разрешен только для loopback-адресов, например localhost и 127.0.0.1.
  • Для loopback-адреса клиент может использовать динамический порт; схема, хост, путь и параметры запроса должны совпадать.
  • Не используйте шаблоны, фрагменты URL и Redirect URI, которыми вы не управляете.

Scope

Scope задают максимальные полномочия приложения. Запрашивайте только необходимые уровни доступа из списка scope REST API.

Права приложения не заменяют обычные права пользователя: даже при наличии scope приложение может работать только с доступными пользователю данными.

Изменение Redirect URI или scope создает новую версию разрешений. Ранее подключенные аккаунты должны проверить и разрешить новую версию, а пользователи — выполнить подключение заново.

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

Приватное партнерское приложение должно быть явно разрешено администратором каждого аккаунта.

  1. Откройте приложение в партнерском кабинете.
  2. В блоке получения ссылки укажите имя клиентского аккаунта.
  3. Скопируйте сформированную ссылку и передайте ее администратору этого аккаунта.
  4. Попросите администратора проверить владельца, Redirect URI и scope, затем разрешить приложение.
  5. После разрешения пользователи аккаунта смогут проходить OAuth-авторизацию. Каждый пользователь отдельно подтверждает доступ от своего имени.

Ссылка ведет в раздел Управление аккаунтом → API → Приложения OAuth и MCP и открывает нужное приложение.

Администратор, который одновременно подключает приложение, может нажать Разрешить и подключить.

Приватное и опубликованное приложение

Статус Как допускается в аккаунт
Приватное Всегда требует явного разрешения администратора каждого аккаунта.
Опубликованное При политике Разрешать опубликованные приложения доступно без отдельного разрешения. При политике Только разрешенные приложения также требует явного разрешения.

Публикация — отдельная проверка ПланФиксом. До подачи приложения подготовьте понятное название и описание, минимальный набор scope, рабочие Redirect URI, и пользовательскую документацию по подключению и удалению интеграции. Уточнить порядок публикации можно в службе поддержки ПланФикса.

Адреса подключения

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



Назначение Адрес
Авторизация https://auth.planfix.com/oauth/authorize
Токен https://auth.planfix.com/oauth/token
Userinfo https://auth.planfix.com/oauth/userinfo
MCP https://mcp.planfix.com/mcp


В глобальный URL не добавляется имя аккаунта. Пользователь выбирает аккаунт на странице ПланФикса. Полный протокол, параметры resource, PKCE, обновление и отзыв токенов описаны в статье OAuth 2.0 для приложений.

Управление приложением

Партнер может:

  • изменить название и описание;
  • изменить Redirect URI и scope;
  • отключить и снова включить приложение;
  • заменить client secret конфиденциального приложения;
  • получить ссылку на разрешение приложения для конкретного аккаунта.

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

Отключение приложения блокирует его OAuth-авторизацию и выданные токены во всех аккаунтах. Это действие затрагивает всех клиентов приложения.

Рекомендации перед запуском

  • Используйте Authorization Code с PKCE S256 и проверяйте state.
  • Запрашивайте только нужные scope.
  • Показывайте пользователю выбранный аккаунт после завершения входа.
  • Обрабатывайте ротацию refresh token: после успешного обновления старый refresh token больше не действует.
  • Не сохраняйте токены, authorization code, code_verifier и client secret в логах.
  • Добавьте в свою документацию способ отключить интеграцию и удалить пользовательские данные.
  • Проверьте сценарии отзыва разрешения, отключения приложения и повторного подключения.

Перейти