Open in

התחברות באמצעות OAuth

אשרו לקוחות MCP ואת ממשק שורת הפקודה של ThunderPhone בלי לשתף מפתח API.

OAuth מאפשר ליישום להתחבר לארגון ThunderPhone אחד עם ההרשאות שתאשרו. לקוחות ספרייה צריכים להשתמש ב-OAuth כברירת מחדל. מפתחות API של ארגון נשארים זמינים ללקוחות שדורשים אסימון Bearer המוגדר ידנית.

אשרו חיבור

התחילו את החיבור בלקוח ה-MCP שלכם. התחברו ל-ThunderPhone, בדקו את שם היישום ואת ההרשאות המבוקשות, בחרו ארגון ובחרו אישור. בחרו דחייה אם לא התחלתם את החיבור או שאינכם סומכים על היישום. שמות יישומים מסופקים על ידי המפתחים שלהם ואינם תג אימות.

הרשאות קריאה חושפות את הנתונים שצוינו, כולל הקלטות ותמלילים כאשר מתבקשת ההרשאה calls:read. הרשאות כתיבה יכולות לשנות או למחוק משאבים; שיחות, קמפיינים, רכישות מספרי טלפון ופריסות עשויים לגרור עלויות או להשפיע על הייצור. תפקידכם בארגון עדיין חל.

לחיבור CLI, פתחו את קישור האימות המוצג במסוף שלכם, השוו את הקוד בן שמונת התווים, בחרו את הארגון שלכם ואשרו. פתיחת הקישור בלבד אינה מעניקה גישה. תוקף הקודים פג לאחר 15 דקות.

נתקו יישום

פתחו בלוח הבקרה את ארגון → מפתחות API → יישומים מורשים ובחרו ביטול הרשאה. פעולה זו מבטלת את ההרשאה שבחרתם עבור הארגון הנוכחי, כולל אסימוני הגישה והרענון שלו. התחברו מחדש מהיישום אם ברצונכם לאשר אותו שוב.

גילוי עבור לקוחות MCP

השתמשו בכתובת השרת 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, אסימוני רענון מתחלפים, רישום דינמי ציבורי של לקוחות, ביטול והרשאת מכשיר. אין סודות לקוח או מענקי implicit. גילוי 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 אם לחשבון אין פרופיל דוא"ל מאומת, במקום לטעון שכתובת דוא"ל לא מאומתת מהימנה. אסימונים לא תקינים, שפגו, שבוטלו או בעלי קהל שגוי מחזירים 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`
זהות החשבון ואימייל מאומת	`openid`, `email` (שניהם נדרשים עבור userinfo)
חיבור מתמשך	`offline_access` (נכלל תמיד)

GET, HEAD ו-OPTIONS משתמשים בתחומי קריאה; שיטות אחרות משתמשות בתחומי כתיבה. שינויים בקולות ובחיוב אינם זמינים דרך OAuth; POST /v1/voices/preview משתמש ב-voices:read מפני שהוא מציג תצוגה מקדימה של קול בלי לשנות את התצורה שלו. כלי MCP אוכפים את התחום של פעולת ה-REST הבסיסית שלהם. העברות בין ארגונים נדחות גם כאשר המשתמש המאשר שייך לשני הארגונים. משפחות API אחרות, כולל ניהול מפתחות API והגדרות חשבון אנושי, אינן זמינות דרך OAuth. הרשאה חסרה בפעולת REST מחזירה 403 עם WWW-Authenticate: Bearer error="insufficient_scope", scope="...". אסימוני גישה לא תקינים או שפג תוקפם מחזירים 401.

אותות אימות של כלי MCP

כל כלי ב-tools/list כולל securitySchemes: [{"type": "oauth2", "scopes": ["agents:read"]}], עם התחום של פעולת ה-REST של הכלי. כלי תיעוד ציבוריים משתמשים ברשימת תחומים ריקה ועדיין דורשים חיבור מאומת.

אסימון תקין שחסר לו התחום של כלי מקבל HTTP 200 עם result של JSON-RPC המכיל isError: true, טקסט הסבר ב-content ו-_meta["mcp/www_authenticate"]. האחרון הוא מערך המכיל אתגר Bearer עם resource_metadata, error="insufficient_scope", error_description וה-scope הנדרש. הכלי אינו מופעל. השתמשו באתגר זה כדי לבקש הסכמה מורחבת. אימות חסר או לא תקין ממשיך להחזיר HTTP 401 עם WWW-Authenticate; כשלי תחום REST ממשיכים להחזיר HTTP 403.

שמירת פרטי גישה

ה-API מריץ python manage.py oauth_cleanup מדי שעה בסביבות staging וייצור. הוא מסיר בקשות הרשאה וקודי מכשיר שפג תוקפם. אסימוני גישה שפג תוקפם, קודי הרשאה וגיבובי אסימוני רענון נגזמים רק לאחר שההענקה שלהם מבוטלת או שכל המשפחה אינה פעילה. גיבובים שנעשה בהם שימוש נשמרים כל עוד למשפחה יש אסימון רענון, קוד הרשאה, קוד מכשיר מאושר או אסימון גישה שניתן להשתמש בהם, כך שהניקוי אינו יכול להשבית זיהוי של הפעלה חוזרת.