--- title: "Forbind med OAuth" description: "Godkend MCP-klienter og ThunderPhone CLI uden at dele en API-nøgle." --- OAuth giver en app mulighed for at oprette forbindelse til én ThunderPhone-organisation med de tilladelser, du godkender. Directory-klienter bør bruge OAuth som standard. Organisations-API-nøgler er fortsat tilgængelige for klienter, der kræver et manuelt konfigureret Bearer-token. ## Godkend en forbindelse Start forbindelsen i din MCP-klient. Log ind på ThunderPhone, kontrollér appnavnet og de anmodede tilladelser, vælg en organisation, og vælg **Godkend**. Vælg **Afvis**, hvis du ikke startede forbindelsen eller ikke har tillid til appen. Appnavne leveres af deres udviklere og er ikke et verificeringsmærke. Læsetilladelser giver adgang til de angivne data, herunder optagelser og transskriptioner, når `calls:read` anmodes om. Skrivetilladelser kan ændre eller slette ressourcer; opkald, kampagner, telefonkøb og udrulninger kan medføre omkostninger eller påvirke produktion. Din organisationsrolle gælder stadig. For en CLI-forbindelse skal du åbne verificeringslinket, der vises i din terminal, sammenligne koden på otte tegn, vælge din organisation og godkende. Det at åbne linket alene giver ikke adgang. Koder udløber efter 15 minutter. ## Afbryd forbindelsen til en app Åbn **Organisation → API-nøgler → Godkendte apps** i dashboardet, og vælg **Tilbagekald**. Dette tilbagekalder din valgte godkendelse for den aktuelle organisation, herunder dens adgangs- og opdateringstokens. Opret forbindelse igen fra appen, hvis du vil godkende den igen. ## Opdagelse for MCP-klienter Brug server-URL'en `https://api.thunderphone.com/v1/mcp`. En anmodning uden gyldig godkendelse modtager `401` med: ```http WWW-Authenticate: Bearer resource_metadata="https://api.thunderphone.com/.well-known/oauth-protected-resource" ``` Hent det dokument, og hent derefter godkendelsesserverens metadata på `https://api.thunderphone.com/.well-known/oauth-authorization-server`. Ressourcemetadata er også tilgængelige på `/.well-known/oauth-protected-resource/v1/mcp`. Brug de returnerede slutpunkter i stedet for at konstruere dem. Ressourceidentifikatoren er `https://api.thunderphone.com/v1/mcp`. Serveren understøtter autorisationskode med **S256 PKCE**, roterende opdateringstokens, offentlig dynamisk klientregistrering, tilbagekaldelse og enhedsgodkendelsestildelingen. Der er ingen klienthemmeligheder eller implicitte tildelinger. OpenID-opdagelse er også tilgængelig på `/.well-known/openid-configuration`; den indeholder de samme felter for godkendelsesserveren plus `subject_types_supported: ["public"]` og userinfo-slutpunktet. ID-tokens og Client ID Metadata Documents (CIMD) understøttes ikke. ### Registrer en offentlig klient Send JSON til `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"] } ``` Gem det returnerede `client_id`. Omdirigeringer skal bruge HTTPS eller HTTP på `127.0.0.1` eller `localhost`. Registrer den nøjagtige callback-URI, herunder dens port og sti. Fragmenter og indlejrede legitimationsoplysninger afvises. Valgfri `client_uri` og `logo_uri` skal bruge HTTPS; ThunderPhone henter dem ikke under registrering. Registrering er hastighedsbegrænset. Registrerede klienter udløber ikke og forbliver registreret, når en forbindelse tilbagekaldes. HTTPS-callbacks omfatter `https://chatgpt.com/connector/oauth/` og `https://chatgpt.com/connector_platform_oauth_redirect`. Hver forbindelse kan registrere sin egen klient. ### Autorisationskode Åbn det opdagede godkendelsesslutpunkt med `client_id`, den nøjagtigt registrerede `redirect_uri`, `response_type=code`, en tilfældig `state`, `scope`, `code_challenge`, `code_challenge_method=S256` og `resource=https://api.thunderphone.com/v1/mcp`. Beregn udfordringen som det upaddede base64url SHA-256-digest af en ny PKCE-verifikator med høj entropi. Kontroller den returnerede `state` og `iss`, før du udveksler koden. Hvert godkendelsessvar, herunder afvisning og protokolfejl, identificerer udstederen med `iss`, som nøjagtigt matcher den opdagede `issuer`. Fejl for en ugyldig klient eller callback returneres lokalt uden omdirigering til den pågældende callback. Udveksl på `POST /v1/oauth/token` med formularindkodning (JSON accepteres også): ```text grant_type=authorization_code client_id= code= redirect_uri= code_verifier= resource=https://api.thunderphone.com/v1/mcp ``` Den valgfri `resource`-parameter accepteres på både godkendelses- og tokenanmodninger, herunder opdaterings- og enhedsudvekslinger. Når den udelades, er standardværdien den opdagede MCP-ressource. Når den er angivet, skal den nøjagtigt matche den ressource; andre værdier returnerer `invalid_target`. Adgangstokens bærer den målgruppe, og MCP afviser tokens med en manglende eller anden målgruppe med `401` og en opdagelsesudfordring. Godkendelsesanmodninger og koder udløber efter 10 minutter. Hvert tokensvar indeholder `access_token`, `token_type` (`Bearer`), `expires_in` (3600 sekunder som standard), `refresh_token`, `scope`, `organization_id` og `organization_name`. Send kun adgangstokens via `Authorization: Bearer`-headeren. Læg aldrig tokens i URL'er, logfiler, kildekontrol eller chat. ### Opdater og tilbagekald Opdater med `grant_type=refresh_token`, `client_id`, `refresh_token` og `resource` på tokenslutpunktet. Gem det nye opdateringstoken atomisk, og stop med at bruge det gamle. Opdateringstokens udløber efter 30 dage uden en vellykket opdatering. En valgfri `scope` kan begrænse de tildelte tilladelser. `offline_access` er altid inkluderet, og opdateringstokens udstedes altid. En indledende anmodning uden `scope` tildeler kun `offline_access`, så klienter bør anmode om de tilladelser, de har brug for. Genbrug af kode og genbrug af roterede opdateringstokens tilbagekalder hele godkendelsen. Serialiser opdateringer i en klient; genafspilning af en legitimationsoplysning, der er blevet udvekslet korrekt, er ikke en sikker genforsøgsstrategi. For at afbryde forbindelsen skal du sende `token` og `client_id` til `POST /v1/oauth/revoke`. Tilbagekaldelse af begge tokens tilbagekalder deres godkendelse, herunder alle tokens udstedt fra dem. Et ukendt token returnerer succes uden at afsløre, om det findes. Dashboard-sessioner kan vise deres egne godkendelser på `GET /v1/oauth/grants` og tilbagekalde en på `DELETE /v1/oauth/grants/`, hvor `X-ThunderPhone-Org` vælger organisationen. ### Enhedsgodkendelse Enhedsgodkendelse er begrænset til forhåndsregistrerede klienter; dynamisk registrerede klienter modtager `unauthorized_client`. Den forhåndsregistrerede offentlige klient `thunderphone-cli` understøtter enhedsgodkendelse og opdatering. Send `client_id=thunderphone-cli` og `scope` til `POST /v1/oauth/device/code`. Vis `user_code` og `verification_uri` til brugeren, eller åbn `verification_uri_complete`. Forespørg tokenslutpunktet med `grant_type=urn:ietf:params:oauth:grant-type:device_code`, `client_id` og `device_code`, og vent mindst det returnerede `interval` (5 sekunder). Fortsæt ved `authorization_pending`. Ved `slow_down` skal du bruge det nye `interval`, der returneres i svaret (øget med 5 sekunder), for hver efterfølgende anmodning. Stop ved `access_denied`, `expired_token` eller enhver anden fejl. Godkend aldrig en enhedskode automatisk. Den forhåndsregistrerede `thunderphone-mcp`-klient accepterer `http://127.0.0.1/callback` og `http://localhost/callback` på enhver port. Skema, vært, sti og forespørgsel skal matche; tokenudvekslingen skal bruge den nøjagtige omdirigerings-URI, herunder port, fra godkendelsen. Dynamisk registrerede klienter kræver nøjagtig matchning af omdirigerings-URI, herunder porten. Registrer dynamisk en anden callback, hvis du har brug for en anden sti. ### Kontoidentitet og kontrol af arbejdsområdedomæne Anmod om både `openid email` sammen med de handlingstilladelser, din klient har brug for. Kald det opdagede `userinfo_endpoint` (`GET /v1/oauth/userinfo`) med adgangstokenet i Bearer-headeren. Et vellykket svar indeholder: ```json { "sub": "123", "email": "person@example.com", "email_verified": true, "name": "Example User", "org_id": 456 } ``` `sub` er den stabile brugeridentifikator; `org_id` er organisationen, der blev valgt under samtykke. Slutpunktet kræver begge identitetstilladelser og returnerer `403`, hvis en af dem mangler. Det returnerer `403` med `error=access_denied`, hvis kontoen ikke har en bekræftet e-mailprofil, frem for at hævde, at en ubekræftet e-mail er betroet. Ugyldige, udløbne, tilbagekaldte eller tokens med forkert målgruppe returnerer `401`. Menneskelige sessionstokens og organisations-API-nøgler kan ikke kalde userinfo. Der udstedes intet ID-token. ## Tilgængelige tilladelser | Familie | Scopes | | --- | --- | | Agenter og agentimporter | `agents:read`, `agents:write` | | Opkald | `calls:read`, `calls:write` | | Telefonnumre, blokerede opkaldere og VoIP | `numbers:read`, `numbers:write` | | Viden | `knowledge:read`, `knowledge:write` | | Kampagner | `campaigns:read`, `campaigns:write` | | Integrationer, webhookslutpunkter, MCP-servere | `integrations:read`, `integrations:write` | | Stemmer | `voices:read` | | Testscenarier, testkørsler, validering | `testing:read`, `testing:write` | | Fakturering | `billing:read` | | Kontoidentitet og bekræftet e-mail | `openid`, `email` (begge påkrævet for userinfo) | | Vedvarende forbindelse | `offline_access` (altid inkluderet) | GET, HEAD og OPTIONS bruger læsescopes; andre metoder bruger skrivescopes. Ændringer af stemmer og fakturering er ikke tilgængelige via OAuth; `POST /v1/voices/preview` bruger `voices:read`, fordi den forhåndsviser en stemme uden at ændre dens konfiguration. MCP-værktøjer håndhæver scopet for deres underliggende REST-handling. Overførsler på tværs af organisationer afvises, selv når den autoriserende bruger tilhører begge organisationer. Andre API-familier, herunder administration af API-nøgler og indstillinger for menneskelige konti, er ikke tilgængelige via OAuth. En manglende tilladelse på en REST-handling returnerer `403` med `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Ugyldige eller udløbne adgangstokens returnerer `401`. ### MCP-værktøjets autentificeringssignaler Alle værktøjer i `tools/list` indeholder `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]` med scopet for værktøjets REST-handling. Offentlige dokumentationsværktøjer bruger en tom scopeliste og kræver stadig en autentificeret forbindelse. Et gyldigt token, der mangler et værktøjs scope, modtager HTTP `200` med et JSON-RPC-`result`, der indeholder `isError: true`, forklarende tekst i `content` og `_meta["mcp/www_authenticate"]`. Sidstnævnte er et array, der indeholder en Bearer-udfordring med `resource_metadata`, `error="insufficient_scope"`, `error_description` og det påkrævede `scope`. Værktøjet udføres ikke. Brug denne udfordring til at anmode om udvidet samtykke. Manglende eller ugyldig autentificering returnerer fortsat HTTP `401` med `WWW-Authenticate`; REST-scopefejl returnerer fortsat HTTP `403`. ## Opbevaring af legitimationsoplysninger API'et kører `python manage.py oauth_cleanup` hver time i staging og produktion. Det fjerner udløbne autorisationsanmodninger og enhedskoder. Udløbne adgangstokens, autorisationskoder og hashes for refresh-tokens beskæres kun, efter deres grant er tilbagekaldt, eller hele familien er inaktiv. Brugte hashes bevares, mens familien har et brugbart refresh-token, en autorisationskode, en godkendt enhedskode eller et adgangstoken, så oprydning ikke kan deaktivere registrering af genafspilning.