Skip to content

OAuth 2.0 для додатків

OAuth 2.0 дає застосунку змогу отримувати доступ до Planfix від імені користувача, не запитуючи й не зберігаючи його пароль.

Planfix використовує потік Authorization Code з обов’язковим PKCE S256. OAuth можна використовувати для підключення до REST API або сервера Planfix 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

Для нових інтеграцій слід використовувати глобальні кінцеві точки. Назва акаунту не входить до цих 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 лише для локальних вузлів, наприклад localhost або 127.0.0.1.

Для локального 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 Токен не містить рівня доступу, потрібного для виконання операції.

Перейти

Отримано з https://planfix.com/uk/help/index.php?title=OAuth_2.0_для_додатків&oldid=10346