Forbind med OAuth

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:

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:

{
  "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/<id> 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å):

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

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/<id>, 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:

{
  "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#

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.