--- title: "Σύνδεση με OAuth" description: "Εξουσιοδοτήστε προγράμματα-πελάτες MCP και το CLI του ThunderPhone χωρίς να κοινοποιήσετε κλειδί 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 και Έγγραφα Μεταδεδομένων Αναγνωριστικού Προγράμματος-Πελάτη (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 base64url ενός νέου επαληθευτή PKCE υψηλής εντροπίας. Ελέγξτε τα επιστρεφόμενα `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` αν ο λογαριασμός δεν έχει επαληθευμένο προφίλ email, αντί να δηλώνει ότι ένα μη επαληθευμένο email είναι έμπιστο. Μη έγκυρα, ληγμένα, ανακλημένα ή διακριτικά με λανθασμένο ακροατήριο επιστρέφουν `401`. Τα διακριτικά ανθρώπινης συνεδρίας και τα κλειδιά API οργανισμού δεν μπορούν να καλέσουν το userinfo. Δεν εκδίδεται διακριτικό ID. ## Διαθέσιμα δικαιώματα | Οικογένεια | Scopes | | --- | --- | | Πράκτορες και εισαγωγές πρακτόρων | `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` | | Ταυτότητα λογαριασμού και επαληθευμένο email | `openid`, `email` (και τα δύο απαιτούνται για userinfo) | | Μόνιμη σύνδεση | `offline_access` (περιλαμβάνεται πάντα) | Τα GET, HEAD και OPTIONS χρησιμοποιούν scopes ανάγνωσης· οι άλλες μέθοδοι χρησιμοποιούν scopes εγγραφής. Οι μεταβολές φωνών και χρέωσης δεν είναι διαθέσιμες μέσω OAuth· το `POST /v1/voices/preview` χρησιμοποιεί `voices:read` επειδή προεπισκοπεί μια φωνή χωρίς να αλλάζει τη διαμόρφωσή της. Τα εργαλεία MCP επιβάλλουν το scope της υποκείμενης λειτουργίας REST. Οι μεταφορές μεταξύ οργανισμών απορρίπτονται ακόμη και όταν ο χρήστης που εγκρίνει ανήκει και στους δύο οργανισμούς. Άλλες οικογένειες API, συμπεριλαμβανομένης της διαχείρισης κλειδιών API και των ρυθμίσεων ανθρώπινων λογαριασμών, δεν είναι διαθέσιμες μέσω OAuth. Η έλλειψη δικαιώματος σε μια λειτουργία REST επιστρέφει `403` με `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`. Τα μη έγκυρα ή ληγμένα διακριτικά πρόσβασης επιστρέφουν `401`. ### Σήματα ελέγχου ταυτότητας εργαλείων MCP Κάθε εργαλείο στο `tools/list` περιλαμβάνει `securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}]`, με το scope της λειτουργίας REST του εργαλείου. Τα εργαλεία δημόσιας τεκμηρίωσης χρησιμοποιούν κενή λίστα scopes και εξακολουθούν να απαιτούν πιστοποιημένη σύνδεση. Ένα έγκυρο διακριτικό στο οποίο λείπει το 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 διατηρούνται όσο η οικογένεια διαθέτει αξιοποιήσιμο διακριτικό ανανέωσης, κωδικό εξουσιοδότησης, εγκεκριμένο κωδικό συσκευής ή διακριτικό πρόσβασης, ώστε ο καθαρισμός να μην μπορεί να απενεργοποιήσει την ανίχνευση επανάληψης.