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

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

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

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

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

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

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

Адреса OAuth

Новые интеграции должны использовать глобальные endpoint. Имя аккаунта в URL указывать не нужно: пользователь выбирает аккаунт во время авторизации.

Назначение	Адрес
Issuer	`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

Redirect URI

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

Допускаются:

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

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

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

Приложение получает только заранее разрешенные уровни доступа — scope. Полный список приведен в статье Список уровней доступа REST API.

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

Для управляемых приложений также доступны служебные scope userinfo, openid и email.

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

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

Пример для 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`	Один из разрешенных Redirect URI.
`response_type`	Значение `code`.
`scope`	Нужные приложению права через пробел. Для REST API параметр обязателен. MCP-клиент может не передавать его — тогда применяется разрешенный приложению набор.
`state`	Случайное значение для защиты от подмены запроса. Приложение обязано проверить его после возврата.
`code_challenge`	Base64url без padding от SHA-256 хеша `code_verifier`.
`code_challenge_method`	Только `S256`.
`resource`	Для MCP — точный URL MCP-сервера. Для REST API параметр не передается.

Для MCP используется resource=https://mcp.planfix.com/mcp.

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

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

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

Authorization code одноразовый и действует 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. Сохраните их и обращайтесь к REST API выбранного аккаунта.

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

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

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

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

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

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

Для запроса userinfo нужен scope openid:

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

Пример ответа при наличии scope email:

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

Глобальная OAuth-авторизация предназначена для сотрудников аккаунта. ПланФикс не выдает 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. Конфиденциальный клиент должен аутентифицироваться своим секретом.

В ответ ПланФикс возвращает новый access token и новый refresh token. Предыдущий refresh token сразу перестает работать, поэтому приложение должно атомарно заменить сохраненное значение.

Отзыв токена

Клиент может отозвать refresh token через /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 в аккаунте.

Совместимость со старыми интеграциями

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

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

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

Ошибка	Причина
`invalid_client`	Неизвестный или отключенный клиент, неверный client secret либо приложение недоступно в выбранном аккаунте.
`invalid_grant`	Code или refresh token недействителен, истек, уже использован либо не соответствует клиенту, Redirect URI, PKCE или ресурсу.
`invalid_scope`	Запрошен scope, не разрешенный приложению.
`invalid_target`	Передан неподдерживаемый `resource` или его значение изменилось между запросами.
`access_denied`	Пользователь отказался от подключения или политика аккаунта не разрешает приложение.
HTTP 401, `invalid_token`	Access token неизвестен, истек или был отозван.
HTTP 403, `insufficient_scope`	У токена нет scope, необходимого для операции.

Навигация

Перейти