--- title: "Повежите се помоћу OAuth-а" description: "Ауторизујте 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` са: ```http 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`: ```json { "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/` и `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): ```text grant_type=authorization_code client_id= code= redirect_uri= code_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/`, при чему `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. Успешан одговор садржи: ```json { "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` сваког сата у припремном и продукционом окружењу. Уклања истекле захтеве за ауторизацију и кодове уређаја. Истекли токени приступа, кодови за ауторизацију и хешеви токена за освежавање уклањају се тек након што се њихова дозвола опозове или цела породица више није активна. Искоришћени хешеви се задржавају док породица има употребљив токен за освежавање, код за ауторизацију, одобрени код уређаја или токен приступа, тако да чишћење не може онемогућити откривање поновљене употребе.