Koble til med OAuth

Autoriser MCP-klienter og ThunderPhone CLI uten å dele en API-nøkkel.

OAuth lar en app koble til én ThunderPhone-organisasjon med tillatelsene du godkjenner. Katalogklienter bør bruke OAuth som standard. API-nøkler for organisasjoner er fortsatt tilgjengelige for klienter som krever et manuelt konfigurert Bearer-token.

Godkjenn en tilkobling#

Start tilkoblingen i MCP-klienten din. Logg på ThunderPhone, kontroller appnavnet og de forespurte tillatelsene, velg en organisasjon og velg Godkjenn. Velg Avslå hvis du ikke startet tilkoblingen eller ikke stoler på appen. Appnavn oppgis av utviklerne deres og er ikke et verifiseringsmerke.

Lesetillatelser gir tilgang til de angitte dataene, inkludert opptak og transkripsjoner når calls:read forespørres. Skrivetillatelser kan endre eller slette ressurser; samtaler, kampanjer, telefonkjøp og utrullinger kan medføre kostnader eller påvirke produksjon. Organisasjonsrollen din gjelder fortsatt.

For en CLI-tilkobling åpner du verifiseringslenken som vises i terminalen, sammenligner den åttesifrede koden, velger organisasjonen din og godkjenner. Å bare åpne lenken gir ikke tilgang. Koder utløper etter 15 minutter.

Koble fra en app#

Åpne Organisasjon → API-nøkler → Autoriserte apper i dashbordet, og velg Tilbakekall. Dette tilbakekaller den valgte autorisasjonen din for gjeldende organisasjon, inkludert tilgangs- og oppdateringstokenene. Koble til på nytt fra appen hvis du vil autorisere den igjen.

Oppdagelse for MCP-klienter#

Bruk server-URL-en https://api.thunderphone.com/v1/mcp. En forespørsel uten gyldig autentisering mottar 401 med:

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

Hent det dokumentet, og hent deretter metadataene til autorisasjonsserveren på https://api.thunderphone.com/.well-known/oauth-authorization-server. Ressursmetadata er også tilgjengelig på /.well-known/oauth-protected-resource/v1/mcp. Bruk de returnerte endepunktene i stedet for å konstruere dem. Ressursidentifikatoren er https://api.thunderphone.com/v1/mcp.

Serveren støtter autorisasjonskode med S256 PKCE, roterende oppdateringstokener, offentlig dynamisk klientregistrering, tilbakekalling og enhetsautorisasjonstilgangen. Det finnes ingen klienthemmeligheter eller implisitte tilganger. OpenID-oppdagelse er også tilgjengelig på /.well-known/openid-configuration; den inkluderer de samme feltene for autorisasjonsserveren, i tillegg til subject_types_supported: ["public"] og userinfo-endepunktet. ID-tokener og Client ID Metadata Documents (CIMD) stø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"]
}

Lagre den returnerte client_id. Omdirigeringer må bruke HTTPS, eller HTTP på 127.0.0.1 eller localhost. Registrer den nøyaktige callback-URI-en, inkludert port og sti. Fragmenter og innebygde påloggingsopplysninger avvises. Valgfri client_uri og logo_uri må bruke HTTPS; ThunderPhone henter dem ikke under registrering. Registrering har hastighetsbegrensning. Registrerte klienter utløper ikke og forblir registrert når en tilkobling tilbakekalles. HTTPS-callbacker inkluderer https://chatgpt.com/connector/oauth/<id> og https://chatgpt.com/connector_platform_oauth_redirect. Hver tilkobling kan registrere sin egen klient.

Autorisasjonskode#

Åpne det oppdagede autorisasjonsendepunktet med client_id, den nøyaktig registrerte redirect_uri, response_type=code, en tilfeldig state, scope, code_challenge, code_challenge_method=S256 og resource=https://api.thunderphone.com/v1/mcp. Beregn utfordringen som den upaddede base64url SHA-256-sammendraget av en ny PKCE-verifikator med høy entropi. Kontroller den returnerte state og iss før du utveksler koden. Hvert autorisasjonssvar, inkludert avslag og protokollfeil, identifiserer utstederen med iss, som må samsvare nøyaktig med den oppdagede issuer. Feil for en ugyldig klient eller callback returneres lokalt uten omdirigering til den callbacken.

Utveksle på POST /v1/oauth/token med skjemakoding (JSON godtas 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 valgfrie parameteren resource godtas på både autorisasjons- og tokenforespørsler, inkludert oppdaterings- og enhetsutvekslinger. Når den utelates, brukes den oppdagede MCP-ressursen som standard. Når den er angitt, må den samsvare nøyaktig med den ressursen; andre verdier returnerer invalid_target. Tilgangstokener har denne målgruppen, og MCP avviser tokener med manglende eller annen målgruppe med 401 og en oppdagelsesutfordring.

Autorisasjonsforespørsler og koder utløper etter 10 minutter. Hvert tokensvar inneholder access_token, token_type (Bearer), expires_in (3600 sekunder som standard), refresh_token, scope, organization_id og organization_name. Send tilgangstokener kun via Authorization: Bearer-headeren. Legg aldri tokener i URL-er, logger, kildekontroll eller chat.

Oppdater og tilbakekall#

Oppdater med grant_type=refresh_token, client_id, refresh_token og resource på tokenendepunktet. Lagre det nye oppdateringstokenet atomisk, og slutt å bruke det gamle. Oppdateringstokener utløper etter 30 dager uten en vellykket oppdatering. En valgfri scope kan begrense de tildelte tillatelsene. offline_access inkluderes alltid, og oppdateringstokener utstedes alltid. En første forespørsel uten scope gir kun offline_access, så klienter bør be om tillatelsene de trenger.

Gjenbruk av kode og gjenbruk av roterte oppdateringstokener tilbakekaller hele autorisasjonen. Serialiser oppdateringer i en klient; å spille av på nytt en legitimasjon som er utvekslet uten feil, er ikke en sikker strategi for nytt forsøk.

For å koble fra sender du token og client_id til POST /v1/oauth/revoke. Tilbakekalling av ett av tokenene tilbakekaller autorisasjonen, inkludert alle tokener utstedt fra det. Et ukjent token returnerer suksess uten å avsløre om det finnes. Dashbordøkter kan liste sine egne autorisasjoner på GET /v1/oauth/grants og tilbakekalle én på DELETE /v1/oauth/grants/<id>, der X-ThunderPhone-Org velger organisasjonen.

Enhetsautorisasjon#

Enhetsautorisasjon er begrenset til forhåndsregistrerte klienter; dynamisk registrerte klienter mottar unauthorized_client. Den forhåndsregistrerte offentlige klienten thunderphone-cli støtter enhetsautorisasjon og oppdatering. Send client_id=thunderphone-cli og scope til POST /v1/oauth/device/code. Vis user_code og verification_uri til brukeren, eller åpne verification_uri_complete.

Poll tokenendepunktet med grant_type=urn:ietf:params:oauth:grant-type:device_code, client_id og device_code, og vent minst det returnerte interval (5 sekunder). Fortsett ved authorization_pending. Ved slow_down bruker du det nye interval som returneres i svaret (økt med 5 sekunder) for hver påfølgende forespørsel. Stopp ved access_denied, expired_token eller en annen feil. Godkjenn aldri en enhetskode automatisk.

Den forhåndsregistrerte klienten thunderphone-mcp godtar http://127.0.0.1/callback og http://localhost/callback på enhver port. Skjema, vert, sti og spørring må samsvare; tokenutvekslingen må bruke den nøyaktige omdirigerings-URI-en, inkludert port, fra autorisasjonen. Dynamisk registrerte klienter krever nøyaktig samsvar for omdirigerings-URI, inkludert port. Registrer en annen callback dynamisk hvis du trenger en annen sti.

Kontoidentitet og kontroll av arbeidsområdedomene#

Be om både openid email sammen med handlingsomfangene klienten din trenger. Kall det oppdagede userinfo_endpoint (GET /v1/oauth/userinfo) med tilgangstokenet i Bearer-headeren. Et vellykket svar inneholder:

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

sub er den stabile brukeridentifikatoren; org_id er organisasjonen som ble valgt under samtykke. Endepunktet krever begge identitetsomfangene og returnerer 403 hvis en av dem mangler. Det returnerer 403 med error=access_denied hvis kontoen ikke har en profil med bekreftet e-post, i stedet for å hevde at en ubekreftet e-post er pålitelig. Ugyldige, utløpte, tilbakekalte eller tokener med feil målgruppe returnerer 401. Tokener for menneskelige økter og organisasjonens API-nøkler kan ikke kalle userinfo. Det utstedes ikke noe ID-token.

Tilgjengelige tillatelser#

GET, HEAD og OPTIONS bruker leseomfang; andre metoder bruker skriveomfang. Endringer i stemmer og fakturering er ikke tilgjengelige via OAuth; POST /v1/voices/preview bruker voices:read fordi den forhåndsviser en stemme uten å endre konfigurasjonen. MCP-verktøy håndhever omfanget til den underliggende REST-operasjonen. Overføringer på tvers av organisasjoner avvises selv når brukeren som autoriserer, tilhører begge organisasjonene. Andre API-familier, inkludert administrasjon av API-nøkler og innstillinger for menneskelige kontoer, er ikke tilgjengelige via OAuth. Manglende tillatelse for en REST-operasjon returnerer 403 med WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Ugyldige eller utløpte tilgangstokener returnerer 401.

Autentiseringssignaler for MCP-verktøy#

Hvert verktøy i tools/list inkluderer securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}], med omfanget til verktøyets REST-operasjon. Offentlige dokumentasjonsverktøy bruker en tom liste over omfang og krever fortsatt en autentisert tilkobling.

Et gyldig token som mangler omfanget til et verktøy, mottar HTTP 200 med et JSON-RPC-result som inneholder isError: true, forklarende tekst i content og _meta["mcp/www_authenticate"]. Sistnevnte er en matrise som inneholder en Bearer-utfordring med resource_metadata, error="insufficient_scope", error_description og det påkrevde scope. Verktøyet kjøres ikke. Bruk denne utfordringen til å be om utvidet samtykke. Manglende eller ugyldig autentisering fortsetter å returnere HTTP 401 med WWW-Authenticate; REST-feil for omfang fortsetter å returnere HTTP 403.

Oppbevaring av påloggingsopplysninger#

API-et kjører python manage.py oauth_cleanup hver time i staging og produksjon. Den fjerner utløpte autorisasjonsforespørsler og enhetskoder. Utløpte tilgangstokener, autorisasjonskoder og hasher for oppdateringstokener fjernes først etter at tildelingen er tilbakekalt eller hele familien er ugyldig. Brukte hasher beholdes så lenge familien har et brukbart oppdateringstoken, en autorisasjonskode, en godkjent enhetskode eller et tilgangstoken, slik at opprydding ikke kan deaktivere deteksjon av gjenbruk.