Open in

Повежите се помоћу OAuth-а

Ауторизујте MCP клијенте и ThunderPhone CLI без дељења 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 токени и документи метаподатака 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 сваког сата у припремном и продукционом окружењу. Уклања истекле захтеве за ауторизацију и кодове уређаја. Истекли токени приступа, кодови за ауторизацију и хешеви токена за освежавање уклањају се тек након што се њихова дозвола опозове или цела породица више није активна. Искоришћени хешеви се задржавају док породица има употребљив токен за освежавање, код за ауторизацију, одобрени код уређаја или токен приступа, тако да чишћење не може онемогућити откривање поновљене употребе.