Open in

Підключення за допомогою OAuth

Авторизуйте клієнти MCP і CLI ThunderPhone без надання ключа API.

OAuth дає змогу застосунку підключатися до однієї організації ThunderPhone із дозволами, які ви схвалюєте. Клієнтам каталогу слід використовувати OAuth за замовчуванням. Ключі API організації залишаються доступними для клієнтів, яким потрібен вручну налаштований токен Bearer.

Схвалення підключення

Почніть підключення у своєму MCP-клієнті. Увійдіть у ThunderPhone, перевірте назву застосунку та запитані дозволи, виберіть організацію й натисніть Схвалити. Виберіть Відхилити, якщо ви не починали підключення або не довіряєте застосунку. Назви застосунків надають їхні розробники, і вони не є позначкою верифікації.

Дозволи на читання надають доступ до вказаних даних, зокрема до записів і транскриптів, коли запитується calls:read. Дозволи на запис можуть змінювати або видаляти ресурси; дзвінки, кампанії, придбання телефонних номерів і розгортання можуть спричинити витрати або вплинути на продакшн. Ваша роль в організації також застосовується.

Для підключення через CLI відкрийте посилання для верифікації, показане у вашому терміналі, порівняйте восьмисимвольний код, виберіть свою організацію та схваліть запит. Саме лише відкриття посилання не надає доступу. Термін дії кодів спливає через 15 хвилин.

Відключення застосунку

Відкрийте Організація → Ключі API → Авторизовані застосунки на панелі керування та виберіть Відкликати. Це відкличе вибрану вами авторизацію для поточної організації, зокрема її токени доступу та оновлення. Повторно підключіться із застосунку, якщо хочете авторизувати його знову.

Виявлення для клієнтів MCP

Використовуйте URL сервера https://api.thunderphone.com/v1/mcp. Запит без дійсної автентифікації отримує 401 із:

WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource"

Отримайте цей документ, а потім отримайте метадані сервера авторизації за адресою https://api.thunderphone.com/.well-known/oauth-authorization-server. Метадані ресурсу також доступні за адресою /.well-known/oauth-protected-resource/v1/mcp. Використовуйте повернені кінцеві точки замість конструювання власних. Ідентифікатор ресурсу — https://api.thunderphone.com/v1/mcp.

Сервер підтримує код авторизації з S256 PKCE, ротацію токенів оновлення, публічну динамічну реєстрацію клієнтів, відкликання та надання авторизації пристрою. Секрети клієнтів і неявні надання не підтримуються. Виявлення OpenID також доступне за адресою /.well-known/openid-configuration; воно містить ті самі поля сервера авторизації, а також subject_types_supported: ["public"] і кінцеву точку userinfo. Токени ID та документи метаданих ідентифікатора клієнта (CIMD) не підтримуються.

Зареєструйте публічний клієнт

Надішліть JSON до POST /v1/oauth/register:

{
  "client_name": "My MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"]
}

Збережіть повернений client_id. Перенаправлення мають використовувати HTTPS або HTTP на 127.0.0.1 чи localhost. Зареєструйте точний URI зворотного виклику, включно з його портом і шляхом. Фрагменти та вбудовані облікові дані відхиляються. Необов’язкові client_uri і logo_uri мають використовувати HTTPS; ThunderPhone не отримує їх під час реєстрації. Для реєстрації застосовується обмеження частоти запитів. Зареєстровані клієнти не мають строку дії та залишаються зареєстрованими після відкликання підключення. HTTPS-зворотні виклики включають https://chatgpt.com/connector/oauth/<id> і https://chatgpt.com/connector_platform_oauth_redirect. Кожне підключення може зареєструвати власний клієнт.

Код авторизації

Відкрийте виявлену кінцеву точку авторизації з client_id, точним зареєстрованим redirect_uri, response_type=code, випадковим state, scope, code_challenge, code_challenge_method=S256 і resource=https://api.thunderphone.com/v1/mcp. Обчисліть виклик як SHA-256-дайджест нового PKCE-верифікатора з високою ентропією у форматі base64url без доповнення. Перевірте повернені state та iss перед обміном коду. Кожна відповідь авторизації, зокрема відмова й помилки протоколу, ідентифікує видавця за допомогою iss, що точно відповідає виявленому issuer. Помилки для недійсного клієнта або зворотного виклику повертаються локально без перенаправлення на цей зворотний виклик.

Виконайте обмін через POST /v1/oauth/token із кодуванням форми (JSON також приймається):

grant_type=authorization_code
client_id=<your client id>
code=<single-use authorization code>
redirect_uri=<exact registered redirect URI>
code_verifier=<original PKCE verifier>
resource=https://api.thunderphone.com/v1/mcp

Необов’язковий параметр resource приймається як у запитах авторизації, так і в запитах токенів (включно з оновленням та обміном для пристрою). Якщо його не вказано, за замовчуванням використовується виявлений ресурс MCP. Якщо його вказано, він має точно відповідати цьому ресурсу; інші значення повертають invalid_target. Токени доступу містять цю аудиторію, а MCP відхиляє токени з відсутньою або іншою аудиторією з 401 і викликом виявлення.

Запити авторизації та коди діють 10 хвилин. Кожна відповідь із токеном містить access_token, token_type (Bearer), expires_in (за замовчуванням 3600 секунд), refresh_token, scope, organization_id і organization_name. Надсилайте токени доступу лише через заголовок Authorization: Bearer. Ніколи не додавайте токени до URL-адрес, журналів, систем контролю версій або чатів.

Оновлення та відкликання

Оновлюйте токен за допомогою grant_type=refresh_token, client_id, refresh_token і resource на кінцевій точці токенів. Атомарно збережіть новий токен оновлення та припиніть використовувати старий. Термін дії токенів оновлення спливає через 30 днів без успішного оновлення. Необов’язковий scope може звузити надані дозволи. offline_access завжди включається, а токени оновлення завжди видаються. Початковий запит без scope надає лише offline_access, тому клієнти мають запитувати потрібні їм дозволи.

Повторне використання коду та повторне використання ротованого токена оновлення відкликають усю авторизацію. Серіалізуйте оновлення в межах клієнта; повторне відтворення успішно обміняних облікових даних не є безпечною стратегією повторної спроби.

Щоб відключитися, надішліть token і client_id до POST /v1/oauth/revoke. Відкликання будь-якого токена відкликає його авторизацію, включно з усіма токенами, виданими на його основі. Невідомий токен повертає успіх без розкриття того, чи існує він. У сесіях панелі керування можна переглядати власні авторизації через GET /v1/oauth/grants і відкликати одну через DELETE /v1/oauth/grants/<id>, де X-ThunderPhone-Org вибирає організацію.

Авторизація пристрою

Авторизація пристрою обмежена попередньо зареєстрованими клієнтами; динамічно зареєстровані клієнти отримують unauthorized_client. Попередньо зареєстрований публічний клієнт thunderphone-cli підтримує авторизацію пристрою та оновлення. Надішліть client_id=thunderphone-cli і scope до POST /v1/oauth/device/code. Покажіть користувачу user_code і verification_uri або відкрийте verification_uri_complete.

Опитуйте кінцеву точку токенів із grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id і device_code, очікуючи щонайменше повернений interval (5 секунд). Продовжуйте при authorization_pending. При slow_down використовуйте новий interval, повернений у відповіді (збільшений на 5 секунд), для кожного наступного запиту. Зупиніться при access_denied, expired_token або будь-якій іншій помилці. Ніколи не схвалюйте код пристрою автоматично.

Попередньо зареєстрований клієнт thunderphone-mcp приймає http://127.0.0.1/callback і http://localhost/callback на будь-якому порту. Схема, хост, шлях і запит мають збігатися; обмін токеном має використовувати точний URI перенаправлення (включно з портом) з авторизації. Динамічно зареєстровані клієнти вимагають точного збігу URI перенаправлення, включно з портом. Динамічно зареєструйте інший зворотний виклик, якщо вам потрібен інший шлях.

Перевірки ідентичності облікового запису та домену робочого простору

Запитуйте обидва openid email разом з областями операцій, потрібними вашому клієнту. Викличте виявлений userinfo_endpoint (GET /v1/oauth/userinfo) із токеном доступу в заголовку Bearer. Успішна відповідь містить:

{
  "sub": "123",
  "email": "person@example.com",
  "email_verified": true,
  "name": "Example User",
  "org_id": 456
}

sub — це стабільний ідентифікатор користувача; org_id — організація, вибрана під час надання згоди. Кінцева точка вимагає обидві області ідентичності та повертає 403, якщо будь-яка з них відсутня. Вона повертає 403 із error=access_denied, якщо обліковий запис не має профілю з підтвердженою електронною поштою, замість твердження, що непідтвердженій електронній пошті можна довіряти. Недійсні, прострочені, відкликані токени або токени з неправильною аудиторією повертають 401. Токени сеансів користувачів і ключі API організації не можуть викликати userinfo. Токен ID не видається.

Доступні дозволи

Категорія	Області доступу
Агенти та імпорт агентів	`agents:read`, `agents:write`
Дзвінки	`calls:read`, `calls:write`
Номери телефонів, заблоковані абоненти та VoIP	`numbers:read`, `numbers:write`
База знань	`knowledge:read`, `knowledge:write`
Кампанії	`campaigns:read`, `campaigns:write`
Інтеграції, кінцеві точки вебхуків, сервери MCP	`integrations:read`, `integrations:write`
Голоси	`voices:read`
Тестові сценарії, запуски тестів, валідація	`testing:read`, `testing:write`
Виставлення рахунків	`billing:read`
Ідентифікація облікового запису та підтверджена електронна пошта	`openid`, `email` (обидва потрібні для userinfo)
Постійне з’єднання	`offline_access` (завжди включено)

GET, HEAD і OPTIONS використовують області доступу для читання; інші методи використовують області доступу для запису. Зміни голосів і рахунків недоступні через OAuth; POST /v1/voices/preview використовує voices:read, оскільки створює попередній перегляд голосу без зміни його конфігурації. Інструменти MCP застосовують область доступу базової REST-операції. Міжорганізаційні перенесення заборонені, навіть якщо користувач, який авторизує дію, належить до обох організацій. Інші категорії API, зокрема керування API-ключами та налаштування облікових записів людей, недоступні через OAuth. Відсутній дозвіл для REST-операції повертає 403 із WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Недійсні або прострочені токени доступу повертають 401.

Сигнали автентифікації інструментів MCP

Кожен інструмент у tools/list містить securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}] з областю доступу REST-операції цього інструмента. Публічні інструменти документації використовують порожній список областей доступу й усе одно потребують автентифікованого з’єднання.

Дійсний токен без області доступу інструмента отримує HTTP 200 із JSON-RPC result, що містить isError: true, пояснювальний текст у content і _meta["mcp/www_authenticate"]. Останній є масивом, що містить Bearer-виклик із resource_metadata, error="insufficient_scope", error_description і потрібною scope. Інструмент не виконується. Використовуйте цей виклик, щоб запросити розширену згоду. Відсутня або недійсна автентифікація і надалі повертає HTTP 401 із WWW-Authenticate; помилки областей доступу REST і надалі повертають HTTP 403.

Зберігання облікових даних

API щогодини запускає python manage.py oauth_cleanup у стейджингу та продакшні. Він видаляє прострочені запити на авторизацію та коди пристроїв. Прострочені токени доступу, коди авторизації та хеші токенів оновлення очищуються лише після відкликання їхнього гранту або завершення всієї родини. Використані хеші зберігаються, доки родина має придатний токен оновлення, код авторизації, схвалений код пристрою або токен доступу, тому очищення не може вимкнути виявлення повторного відтворення.