OAuth 2.0 для приложений

OAuth 2.0 позволяет приложению получать доступ к Planfix от имени пользователя, не запрашивая и не сохраняя его пароль.

В Planfix используется поток Authorization Code с обязательным PKCE S256. OAuth можно использовать для подключения к REST API или к серверу Planfix MCP.

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

Варианты регистрации приложения

Вариант	Когда использовать	Где работает
Приложение, принадлежащее аккаунту	Интеграция предназначена для одного аккаунта, а клиенту требуется заранее заданный client_id.	Только в аккаунте, которому оно принадлежит.
Приложение, принадлежащее партнёру	Одно и то же приложение должно подключаться к нескольким аккаунтам клиентов.	В аккаунтах, где это разрешено политикой безопасности или администратором.
Автоматическая регистрация MCP-клиента	MCP-клиент поддерживает документ метаданных Client ID (CIMD) или динамическую регистрацию клиента (DCR).	Сама по себе регистрация не предоставляет доступ к аккаунту. Приложение всё равно должно быть разрешено в выбранном аккаунте.

CIMD и DCR доступны только для подключений MCP. Для REST API используйте приложение, принадлежащее аккаунту или партнёру.

Конечные точки OAuth

Для новых интеграций следует использовать глобальные конечные точки. В этих URL не указывается имя аккаунта: пользователь выбирает аккаунт во время авторизации.

Назначение	Адрес
Издатель	https://auth.planfix.com
Авторизация	https://auth.planfix.com/oauth/authorize
Токен	https://auth.planfix.com/oauth/token
Информация о пользователе	https://auth.planfix.com/oauth/userinfo
Отзыв токена	https://auth.planfix.com/oauth/revoke
Динамическая регистрация MCP-клиента	https://auth.planfix.com/oauth/register

Метаданные сервера авторизации доступны по стандартным конечным точкам:

https://auth.planfix.com/.well-known/oauth-authorization-server
https://auth.planfix.com/.well-known/openid-configuration

URI перенаправления

URI перенаправления должен быть зарегистрирован в настройках приложения. Значение, переданное в запросе авторизации, должно совпадать с одним из зарегистрированных URI.

Разрешены:

• URL с протоколом https;
• URL с протоколом http только для loopback-хостов, например localhost или 127.0.0.1.

Для loopback URI порт может быть динамическим, но схема, хост, путь и запрос должны совпадать. Фрагменты URL и пользовательские данные в URL не допускаются.

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

Приложение получает только те уровни доступа, или scopes, которые были разрешены заранее. Полный список см. в разделе Уровни доступа к REST API.

Запрошенный набор должен быть подмножеством областей доступа, зарегистрированных для приложения. Области доступа приложения не расширяют права пользователя в Planfix: приложение может получать доступ только к данным, доступным Сотруднику, который его подключил.

Управляемые приложения также получают служебные области доступа userinfo, openid и email.

Авторизация пользователя

Сгенерируйте code_verifier и его представление в виде хеша SHA-256 — code_challenge, а затем откройте конечную точку авторизации в браузере.

Пример для REST API:

GET https://auth.planfix.com/oauth/authorize
    ?client_id=CLIENT_ID
    &redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
    &response_type=code
    &scope=openid%20email%20task_readonly
    &state=RANDOM_STATE
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

Для MCP добавьте параметр resource с точным URL сервера MCP:

resource=https%3A%2F%2Fmcp.planfix.com%2Fmcp

Параметр	Описание
client_id	Идентификатор зарегистрированного приложения. Для CIMD это URL документа метаданных клиента.
redirect_uri	Один из разрешённых URI перенаправления.
response_type	Должен иметь значение code.
scope	Необходимые разрешения, разделённые пробелами. Для REST API этот параметр обязателен. MCP-клиент может его не указывать — в этом случае используются области доступа, разрешённые для приложения.
state	Случайное значение, защищающее запрос от подмены. После перенаправления приложение должно проверить это значение.
code_challenge	Хеш SHA-256 от code_verifier в формате Base64url без заполнения.
code_challenge_method	Поддерживается только S256.
resource	Для MCP — точный URL https://mcp.planfix.com/mcp. Не передавайте этот параметр для REST API.

Пользователь выбирает аккаунт, входит в систему и проверяет запрошенные разрешения. Приложение, принадлежащее аккаунту, сразу открывает аккаунт-владелец. Если политика безопасности требует одобрения администратора, Planfix отображает соответствующий шаг. Администратор может одобрить приложение и подключить его одним действием.

После успешной авторизации Planfix перенаправляет браузер на redirect_uri:

https://example.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE&iss=https%3A%2F%2Fauth.planfix.com

Код авторизации можно использовать только один раз; срок его действия — 10 минут.

Получение токенов

Отправьте POST-запрос к /oauth/token, используя тип содержимого application/x-www-form-urlencoded:

grant_type=authorization_code
&client_id=CLIENT_ID
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Foauth%2Fcallback
&code_verifier=CODE_VERIFIER

Для MCP повторно передайте параметр resource с тем же значением, что и в запросе авторизации.

Публичный клиент отправляет запрос без секрета. Конфиденциальный клиент также проходит аутентификацию с помощью client_secret_basic или параметров client_id и client_secret в теле запроса.

Пример ответа:

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 86400,
  "refresh_token": "REFRESH_TOKEN",
  "scope": "openid email task_readonly"
}

Для REST API ответ также содержит account_name, account_domain и account_url. Сохраните эти значения и используйте URL выбранного аккаунта для запросов к REST API.

Токен доступа действителен в течение 24 часов. Он привязан к пользователю, аккаунту, приложению, областям доступа и ресурсу. Токен, выданный для MCP, нельзя напрямую использовать с REST API, а токен REST API нельзя использовать с MCP.

Использование токена с REST API

Передайте токен в заголовке Authorization:

GET https://account.planfix.com/rest/task/123
Authorization: Bearer ACCESS_TOKEN

Используйте URL аккаунта, возвращённый при обмене кода авторизации на токены. Доступны только методы, предусмотренные выданными областями доступа. На OAuth-токены распространяются ограничения тарифного плана аккаунта и стандартные ограничения REST API.

Информация о пользователе

Для запроса userinfo требуется область доступа openid:

GET https://auth.planfix.com/oauth/userinfo
Authorization: Bearer ACCESS_TOKEN

Пример ответа при наличии области доступа email:

{
  "sub": "123:user:456",
  "email": "user@example.com",
  "email_verified": true
}

Глобальная авторизация OAuth доступна Сотрудникам аккаунта. Planfix не выдаёт id_token; вместо этого запрашивайте данные пользователя через userinfo.

Обновление токенов

POST https://auth.planfix.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&client_id=CLIENT_ID
&refresh_token=REFRESH_TOKEN

Для MCP повторно передайте тот же параметр resource. Конфиденциальный клиент должен пройти аутентификацию с помощью своего секрета.

Planfix возвращает новый токен доступа и новый токен обновления. Предыдущий токен обновления немедленно становится недействительным, поэтому приложение должно атомарно заменить сохранённое значение.

Отзыв токена

Клиент может отозвать токен обновления через /oauth/revoke:

POST https://auth.planfix.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=REFRESH_TOKEN
&client_id=CLIENT_ID

Пользователь также может удалить подключение в разделе Управление сеансами карточки пользователя. Администратор может отозвать разрешение стороннего приложения для всего аккаунта. См. Приложения OAuth и MCP в аккаунте.

Совместимость с существующими интеграциями

Конечные точки для отдельных аккаунтов, например https://account.planfix.com/api/v2/oauth/authorize, /token и /userinfo, продолжат работать для существующих интеграций, привязанных к определённому аккаунту.

Для новых интеграций используйте глобальные конечные точки. Они поддерживают стандартное обнаружение метаданных, выбор аккаунта и MCP. Не смешивайте глобальные конечные точки и конечные точки для отдельных аккаунтов в рамках одного сеанса OAuth.

Рекомендации по безопасности

• Всегда используйте PKCE S256 и проверяйте state.
• Для мобильных, настольных и браузерных приложений используйте публичный клиент без секрета.
• Используйте конфиденциальный клиент только в том случае, если секрет можно безопасно хранить на сервере.
• Запрашивайте минимально необходимый набор областей доступа.
• Не записывайте в журналы токены доступа и обновления, коды авторизации, code_verifier и секреты клиента.
• Храните токены обновления и секреты клиента в зашифрованном хранилище.
• Проверяйте iss в ответе и принимайте только ожидаемый издатель Planfix.

Возможные ошибки

Ошибка	Причина
invalid_client	Клиент неизвестен или отключён, секрет клиента указан неверно либо приложение недоступно в выбранном аккаунте.
invalid_grant	Код авторизации или токен обновления недействителен, срок его действия истёк, он уже использован либо не соответствует клиенту, URI перенаправления, данным PKCE или ресурсу.
invalid_scope	Запрос содержит область доступа, не разрешённую для приложения.
invalid_target	Ресурс resource не поддерживается или изменился между запросами.
access_denied	Пользователь отклонил подключение или политика аккаунта не разрешает использовать приложение.
HTTP 401, invalid_token	Токен доступа неизвестен, срок его действия истёк или он отозван.
HTTP 403, insufficient_scope	Токен не содержит область доступа, необходимую для выполнения операции.

Перейти

• MCP
• Приложения OAuth и MCP в аккаунте
• OAuth-приложения для партнеров
• REST API
• REST API Авторизация
• REST API Список уровней доступа – scope