Open in
Σύνδεση με OAuth
Εξουσιοδοτήστε προγράμματα-πελάτες MCP και το CLI του ThunderPhone χωρίς να κοινοποιήσετε κλειδί API.
Το OAuth επιτρέπει σε μια εφαρμογή να συνδεθεί με έναν οργανισμό ThunderPhone με τα δικαιώματα που εγκρίνετε. Οι πελάτες καταλόγου θα πρέπει να χρησιμοποιούν OAuth από προεπιλογή. Τα κλειδιά API οργανισμού παραμένουν διαθέσιμα για πελάτες που απαιτούν ένα μη αυτόματα διαμορφωμένο διακριτικό Bearer.
Εγκρίνετε μια σύνδεση
Ξεκινήστε τη σύνδεση στον πελάτη MCP σας. Συνδεθείτε στο ThunderPhone, ελέγξτε το όνομα της εφαρμογής και τα ζητούμενα δικαιώματα, επιλέξτε έναν οργανισμό και επιλέξτε Έγκριση. Επιλέξτε Απόρριψη εάν δεν ξεκινήσατε εσείς τη σύνδεση ή δεν εμπιστεύεστε την εφαρμογή. Τα ονόματα εφαρμογών παρέχονται από τους προγραμματιστές τους και δεν αποτελούν σήμα επαλήθευσης.
Τα δικαιώματα ανάγνωσης εκθέτουν τα ονομαστικά δεδομένα, συμπεριλαμβανομένων εγγραφών και απομαγνητοφωνήσεων όταν ζητείται το calls:read. Τα δικαιώματα εγγραφής μπορούν να αλλάξουν ή να διαγράψουν πόρους· οι κλήσεις, οι καμπάνιες, οι αγορές τηλεφωνικών αριθμών και οι αναπτύξεις μπορούν να επιφέρουν χρεώσεις ή να επηρεάσουν την παραγωγή. Ο ρόλος σας στον οργανισμό εξακολουθεί να ισχύει.
Για σύνδεση CLI, ανοίξτε τον σύνδεσμο επαλήθευσης που εμφανίζεται στο τερματικό σας, συγκρίνετε τον οκταψήφιο κωδικό, επιλέξτε τον οργανισμό σας και εγκρίνετε. Το απλό άνοιγμα του συνδέσμου δεν εκχωρεί πρόσβαση. Οι κωδικοί λήγουν μετά από 15 λεπτά.
Αποσυνδέστε μια εφαρμογή
Ανοίξτε Ρυθμίσεις → Ασφάλεια → Εφαρμογές που έχετε συνδέσει και επιλέξτε Αποσύνδεση δίπλα στην εφαρμογή. Με αυτό ανακαλείται η εξουσιοδότησή σας για τον τρέχοντα οργανισμό, συμπεριλαμβανομένων των διακριτικών πρόσβασης και ανανέωσης της. Επανασυνδεθείτε από την εφαρμογή, αν θέλετε να την εξουσιοδοτήσετε ξανά.
Η αλλαγή ή επαναφορά του κωδικού πρόσβασής σας ή η αλλαγή του email του λογαριασμού σας σας αποσυνδέει παντού: ανακαλεί επίσης την πρόσβαση κάθε εφαρμογής που έχετε εξουσιοδοτήσει, σε κάθε οργανισμό, συμπεριλαμβανομένων των συνδέσεων MCP, του Zapier και του CLI. Επανασυνδέστε κάθε εφαρμογή στη συνέχεια.
Τα τελικά σημεία webhook που δημιούργησε μια εφαρμογή συνεχίζουν να παραδίδουν συμβάντα μετά την ανάκληση της πρόσβασής της, μέχρι να τα διαγράψετε. Μετά από υποψία κλοπής λογαριασμού, καταγράψτε τα με GET /v1/developer/webhook-endpoints χρησιμοποιώντας ένα κλειδί API διαχειριστή και διαγράψτε όσα δεν αναγνωρίζετε· ο πίνακας ελέγχου εμφανίζει κάθε τελικό σημείο, συμπεριλαμβανομένων εκείνων ενός πράκτορα, στην ενότητα Ενσωματώσεις → Webhooks.
Εντοπισμός για προγράμματα-πελάτες 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 και Έγγραφα Μεταδεδομένων Αναγνωριστικού Προγράμματος-Πελάτη (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 base64url ενός νέου επαληθευτή PKCE υψηλής εντροπίας. Ελέγξτε τα επιστρεφόμενα 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 αν ο λογαριασμός δεν έχει επαληθευμένο προφίλ email, αντί να δηλώνει ότι ένα μη επαληθευμένο email είναι έμπιστο. Μη έγκυρα, ληγμένα, ανακλημένα ή διακριτικά με λανθασμένο ακροατήριο επιστρέφουν 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 |
| Ενσωματώσεις, τελικά σημεία webhook, διακομιστές MCP | integrations:read, integrations:write |
| Φωνές | voices:read |
| Σενάρια δοκιμών, εκτελέσεις δοκιμών, επικύρωση | testing:read, testing:write |
| Χρέωση | billing:read |
| Ρυθμίσεις οργανισμού (μόνο εργαλεία MCP) | org:read, org:write |
| Ταυτότητα λογαριασμού και επαληθευμένο email | openid, email (και τα δύο απαιτούνται για το userinfo) |
| Μόνιμη σύνδεση | offline_access (περιλαμβάνεται πάντα) |
Τα GET, HEAD και OPTIONS χρησιμοποιούν εύρη ανάγνωσης· οι άλλες μέθοδοι χρησιμοποιούν εύρη εγγραφής. Οι μεταβολές φωνών και χρέωσης δεν είναι διαθέσιμες μέσω OAuth· τρία αιτήματα POST δεν αλλάζουν τίποτα και χρησιμοποιούν εύρη ανάγνωσης: το POST /v1/voices/preview (voices:read) προεπισκοπεί μια φωνή, το POST /v1/knowledge/.../search (knowledge:read) υποβάλλει ερώτημα σε μια βάση γνώσεων και το POST /v1/calls/bulk-delete/preview (calls:read) μετρά τι άλλο θα αφαιρούσε η διαγραφή αυτών των κλήσεων. Τα εργαλεία MCP επιβάλλουν το εύρος της υποκείμενης λειτουργίας REST· τα εργαλεία MCP χωρίς μία μόνο λειτουργία REST ονομάζουν το δικό τους εύρος (για παράδειγμα, org:read για το get_org_settings, numbers:write για το unblock_callers). Τα org:read και org:write δεν ανοίγουν καμία διαδρομή REST. Οι μεταφορές μεταξύ οργανισμών απορρίπτονται ακόμη και όταν ο χρήστης που παρέχει την εξουσιοδότηση ανήκει και στους δύο οργανισμούς. Άλλες οικογένειες API, συμπεριλαμβανομένης της διαχείρισης κλειδιών API και των ρυθμίσεων λογαριασμών χρηστών, δεν είναι διαθέσιμες μέσω OAuth. Η έλλειψη δικαιώματος σε μια λειτουργία REST επιστρέφει 403 με WWW-Authenticate: Bearer error="insufficient_scope", scope="...". Τα μη έγκυρα ή ληγμένα διακριτικά πρόσβασης επιστρέφουν 401.
Σήματα ελέγχου ταυτότητας εργαλείων MCP
Κάθε εργαλείο στο tools/list περιλαμβάνει το securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}], με το εύρος της λειτουργίας REST του συγκεκριμένου εργαλείου. Τα εργαλεία δημόσιας τεκμηρίωσης, get_supported_languages, get_agent_capabilities, escalate_to_human και request_feature χρησιμοποιούν κενή λίστα εύρους και εξακολουθούν να απαιτούν πιστοποιημένη σύνδεση.
Ένα έγκυρο διακριτικό στο οποίο λείπει το scope ενός εργαλείου λαμβάνει 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· οι αποτυχίες scope REST συνεχίζουν να επιστρέφουν HTTP 403.
Διατήρηση διαπιστευτηρίων
Το API εκτελεί python manage.py oauth_cleanup κάθε ώρα στα περιβάλλοντα staging και παραγωγής. Καταργεί ληγμένα αιτήματα εξουσιοδότησης και κωδικούς συσκευής. Τα ληγμένα διακριτικά πρόσβασης, οι κωδικοί εξουσιοδότησης και τα hashes διακριτικών ανανέωσης εκκαθαρίζονται μόνο αφού ανακληθεί η εκχώρησή τους ή ολόκληρη η οικογένεια δεν είναι πλέον ενεργή. Τα χρησιμοποιημένα hashes διατηρούνται όσο η οικογένεια διαθέτει αξιοποιήσιμο διακριτικό ανανέωσης, κωδικό εξουσιοδότησης, εγκεκριμένο κωδικό συσκευής ή διακριτικό πρόσβασης, ώστε ο καθαρισμός να μην μπορεί να απενεργοποιήσει την ανίχνευση επανάληψης.