टीवी और सीमित इनपुट वाले डिवाइस ऐप्लिकेशन के लिए OAuth 2.0

इस दस्तावेज़ में, टीवी, गेम कंसोल, और प्रिंटर जैसे डिवाइसों पर चलने वाले ऐप्लिकेशन के ज़रिए, YouTube Data API को ऐक्सेस करने के लिए, OAuth 2.0 अनुमति को लागू करने का तरीका बताया गया है. खास तौर पर, यह फ़्लो उन डिवाइसों के लिए डिज़ाइन किया गया है जिनके पास ब्राउज़र का ऐक्सेस नहीं है या जिनमें इनपुट की सुविधाएं सीमित हैं.

OAuth 2.0 की मदद से, उपयोगकर्ता अपने उपयोगकर्ता नाम, पासवर्ड, और अन्य जानकारी को निजी रखते हुए, किसी ऐप्लिकेशन के साथ खास डेटा शेयर कर सकते हैं. उदाहरण के लिए, कोई टीवी ऐप्लिकेशन, Google Drive पर सेव की गई फ़ाइल चुनने की अनुमति पाने के लिए, OAuth 2.0 का इस्तेमाल कर सकता है.

इस फ़्लो का इस्तेमाल करने वाले ऐप्लिकेशन, अलग-अलग डिवाइसों पर उपलब्ध कराए जाते हैं. इसलिए, यह माना जाता है कि ऐप्लिकेशन गोपनीय जानकारी को सुरक्षित नहीं रख सकते. जब उपयोगकर्ता ऐप्लिकेशन का इस्तेमाल कर रहा हो या ऐप्लिकेशन बैकग्राउंड में चल रहा हो, तब वे Google API ऐक्सेस कर सकते हैं.

विकल्प

अगर आपको Android, iOS, macOS, Linux या Windows (इसमें Universal Windows Platform भी शामिल है) जैसे किसी ऐसे प्लैटफ़ॉर्म के लिए ऐप्लिकेशन बनाना है जिसके पास ब्राउज़र और पूरी इनपुट सुविधाओं का ऐक्सेस है, तो मोबाइल और डेस्कटॉप ऐप्लिकेशन के लिए OAuth 2.0 फ़्लो का इस्तेमाल करें. (आपको उस फ़्लो का इस्तेमाल तब भी करना चाहिए, जब आपका ऐप्लिकेशन ग्राफ़िकल इंटरफ़ेस के बिना, कमांड-लाइन वाला टूल हो.)

अगर आपको सिर्फ़ उपयोगकर्ताओं को उनके Google खातों से साइन इन कराना है और उपयोगकर्ता की प्रोफ़ाइल की बुनियादी जानकारी पाने के लिए, JWT आईडी टोकन का इस्तेमाल करना है, तो टीवी और सीमित इनपुट डिवाइसों पर साइन इन करने के बारे में जानें.

ज़रूरी शर्तें

अपने प्रोजेक्ट के लिए एपीआई चालू करना

Google API को कॉल करने वाले किसी भी ऐप्लिकेशन को, उन एपीआई को में चालू करना होगा.

अपने प्रोजेक्ट के लिए एपीआई चालू करने के लिए:

1. में .
3. YouTube Data API ढूंढने और उसे चालू करने के लिए, लाइब्रेरी पेज का इस्तेमाल करें. ऐसे अन्य एपीआई ढूंढें जिनका इस्तेमाल आपका ऐप्लिकेशन करेगा और उन्हें भी चालू करें.

अनुमति देने वाले क्रेडेंशियल बनाना

Google के एपीआई को ऐक्सेस करने के लिए OAuth 2.0 का इस्तेमाल करने वाले किसी भी ऐप्लिकेशन के पास, अनुमति देने वाले ऐसे क्रेडेंशियल होने चाहिए जिनसे Google के OAuth 2.0 सर्वर को ऐप्लिकेशन की पहचान की जा सके. यहां अपने प्रोजेक्ट के लिए क्रेडेंशियल बनाने का तरीका बताया गया है. इसके बाद, आपके ऐप्लिकेशन उन एपीआई को ऐक्सेस करने के लिए क्रेडेंशियल का इस्तेमाल कर सकते हैं जिन्हें आपने उस प्रोजेक्ट के लिए चालू किया है.

2. क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी पर क्लिक करें.
3. टीवी और सीमित इनपुट डिवाइस के लिए ऐप्लिकेशन टाइप चुनें.
4. अपने OAuth 2.0 क्लाइंट को नाम दें और बनाएं पर क्लिक करें.

ऐक्सेस के स्कोप की पहचान करना

स्कोप की मदद से, आपके ऐप्लिकेशन को सिर्फ़ उन संसाधनों का ऐक्सेस पाने का अनुरोध करने की सुविधा मिलती है जिनकी उसे ज़रूरत होती है. साथ ही, इससे उपयोगकर्ताओं को यह कंट्रोल करने की सुविधा भी मिलती है कि वे आपके ऐप्लिकेशन को कितना ऐक्सेस दें. इसलिए, अनुरोध किए गए स्कोप की संख्या और उपयोगकर्ता की सहमति पाने की संभावना के बीच उलटा संबंध हो सकता है.

हमारा सुझाव है कि OAuth 2.0 ऑथराइज़ेशन लागू करने से पहले, उन स्कोप की पहचान करें जिन्हें ऐक्सेस करने के लिए आपके ऐप्लिकेशन को अनुमति की ज़रूरत होगी.

YouTube Data API v3, इन स्कोप का इस्तेमाल करता है:

इंस्टॉल किए गए ऐप्लिकेशन या डिवाइसों के लिए, अनुमति वाले स्कोप की सूची देखें.

OAuth 2.0 ऐक्सेस टोकन पाना

भले ही, आपका ऐप्लिकेशन सीमित इनपुट सुविधाओं वाले डिवाइस पर चलता हो, लेकिन अनुमति देने का यह फ़्लो पूरा करने के लिए, उपयोगकर्ताओं के पास बेहतर इनपुट सुविधाओं वाले डिवाइस का अलग ऐक्सेस होना चाहिए. इस फ़्लो में ये चरण शामिल हैं:

1. आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर को एक अनुरोध भेजता है. इससे उन स्कोप की पहचान होती है जिन्हें ऐक्सेस करने के लिए आपका ऐप्लिकेशन अनुमति का अनुरोध करेगा.
2. सर्वर, डिवाइस कोड और उपयोगकर्ता कोड जैसी कई जानकारी के साथ जवाब देता है. इस जानकारी का इस्तेमाल अगले चरणों में किया जाता है.
3. आपने ऐसी जानकारी दिखाई है जिसे उपयोगकर्ता किसी दूसरे डिवाइस पर डालकर, आपके ऐप्लिकेशन को अनुमति दे सकता है.
4. आपका ऐप्लिकेशन, Google के अनुमति देने वाले सर्वर से अनुरोध करना शुरू कर देता है. इससे यह पता चलता है कि उपयोगकर्ता ने आपके ऐप्लिकेशन को अनुमति दी है या नहीं.
5. उपयोगकर्ता, बेहतर इनपुट सुविधाओं वाले डिवाइस पर स्विच करता है, वेब ब्राउज़र लॉन्च करता है, और तीसरे चरण में दिखाए गए यूआरएल पर जाता है. इसके बाद, वह तीसरे चरण में दिखाया गया कोड डालता है. इसके बाद, उपयोगकर्ता आपके ऐप्लिकेशन को ऐक्सेस करने की अनुमति दे सकता है या उसे अस्वीकार कर सकता है.
6. पोलिंग के अनुरोध के अगले जवाब में वे टोकन शामिल होते हैं जिनकी ज़रूरत आपके ऐप्लिकेशन को, उपयोगकर्ता की ओर से अनुरोधों को अनुमति देने के लिए होती है. (अगर उपयोगकर्ता ने आपके ऐप्लिकेशन का ऐक्सेस देने से मना कर दिया है, तो रिस्पॉन्स में टोकन शामिल नहीं होते.)

इस प्रोसेस के बारे में नीचे दी गई इमेज में बताया गया है:

इन चरणों के बारे में ज़्यादा जानकारी, नीचे दिए गए सेक्शन में दी गई है. डिवाइसों में मौजूद सुविधाओं और रनटाइम के कई तरह के एनवायरमेंट को ध्यान में रखते हुए, इस दस्तावेज़ में दिए गए उदाहरणों में curl कमांड लाइन की सुविधा का इस्तेमाल किया गया है. इन उदाहरणों को अलग-अलग भाषाओं और रनटाइम में आसानी से पोर्ट किया जा सकता है.

पहला चरण: डिवाइस और उपयोगकर्ता कोड का अनुरोध करना

इस चरण में, आपका डिवाइस https://oauth2.googleapis.com/device/code पर, Google के अनुमति देने वाले सर्वर को एचटीटीपी पोस्ट अनुरोध भेजता है. इससे आपके ऐप्लिकेशन के साथ-साथ, उन ऐक्सेस स्कोप की पहचान होती है जिन्हें आपका ऐप्लिकेशन उपयोगकर्ता की ओर से ऐक्सेस करना चाहता है. आपको device_authorization_endpoint मेटाडेटा वैल्यू का इस्तेमाल करके, डिस्कवरी दस्तावेज़ से यह यूआरएल पाना चाहिए. एचटीटीपी अनुरोध के इन पैरामीटर को शामिल करें:

उदाहरण

यहां दिया गया स्निपेट, अनुरोध का सैंपल दिखाता है:

POST /device/code HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl

इस उदाहरण में, एक ही अनुरोध भेजने के लिए curl कमांड दिखाया गया है:

curl -d "client_id=client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.force-ssl" \
     https://oauth2.googleapis.com/device/code

दूसरा चरण: अनुमति देने वाले सर्वर से मिले जवाब को मैनेज करना

ऑथराइज़ेशन सर्वर इनमें से कोई एक रिस्पॉन्स दिखाएगा:

सफलता का जवाब

अगर अनुरोध मान्य है, तो आपको JSON ऑब्जेक्ट के तौर पर रिस्पॉन्स मिलेगा. इसमें ये प्रॉपर्टी शामिल होंगी:

यहां दिया गया स्निपेट, जवाब का एक सैंपल दिखाता है:

{
  "device_code": "4/4-GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
  "user_code": "GQVQ-JKEC",
  "verification_url": "https://www.google.com/device",
  "expires_in": 1800,
  "interval": 5
}

कोटा से ज़्यादा अनुरोध होने पर दिखने वाला जवाब

अगर आपके डिवाइस कोड के अनुरोध, आपके क्लाइंट आईडी से जुड़े कोटे से ज़्यादा हो गए हैं, तो आपको 403 कोड वाला जवाब मिलेगा. इसमें यह गड़बड़ी दिखेगी:

{
  "error_code": "rate_limit_exceeded"
}

ऐसे में, अनुरोधों की दर को कम करने के लिए, बैकऑफ़ की रणनीति का इस्तेमाल करें.

तीसरा चरण: उपयोगकर्ता को कोड दिखाना

उपयोगकर्ता को दूसरे चरण में मिले verification_url और user_code दिखाएं. दोनों वैल्यू में, US-ASCII वर्ण सेट से प्रिंट किया जा सकने वाला कोई भी वर्ण शामिल हो सकता है. उपयोगकर्ता को दिखाए जाने वाले कॉन्टेंट में, उसे किसी दूसरे डिवाइस पर verification_url पर नेविगेट करने और user_code डालने का निर्देश देना चाहिए.

अपने यूज़र इंटरफ़ेस (यूआई) को इन नियमों को ध्यान में रखकर डिज़ाइन करें:

• user_code
  • user_code को ऐसे फ़ील्ड में दिखाया जाना चाहिए जिसमें 15 'W' साइज़ के वर्णों को दिखाया जा सकता हो. दूसरे शब्दों में, अगर कोड WWWWWWWWWWWWWWW को सही तरीके से दिखाया जा सकता है, तो आपका यूज़र इंटरफ़ेस मान्य है. हमारा सुझाव है कि user_code को आपके यूज़र इंटरफ़ेस में दिखाने के तरीके की जांच करते समय, उस स्ट्रिंग वैल्यू का इस्तेमाल करें.
  • user_code केस-सेंसिटिव (बड़े और छोटे अक्षरों में अंतर) होता है. इसमें किसी भी तरह का बदलाव नहीं किया जाना चाहिए. जैसे, केस बदलना या फ़ॉर्मैटिंग के अन्य वर्ण डालना.
• verification_url
  • verification_url दिखाने के लिए, स्पेस काफ़ी बड़ा होना चाहिए, ताकि उसमें 40 वर्णों की यूआरएल स्ट्रिंग को दिखाया जा सके.
  • आपको verification_url में किसी भी तरह का बदलाव नहीं करना चाहिए. हालांकि, डिसप्ले के लिए स्कीम को हटाया जा सकता है. अगर आपको डिसप्ले से जुड़ी वजहों से, यूआरएल से स्कीम (उदाहरण के लिए, https://) हटानी है, तो पक्का करें कि आपका ऐप्लिकेशन http और https, दोनों वैरिएंट को हैंडल कर सकता हो.

चौथा चरण: Google के अनुमति देने वाले सर्वर से अनुरोध करना

उपयोगकर्ता, verification_url पर जाने और ऐक्सेस देने (या अस्वीकार करने) के लिए, किसी दूसरे डिवाइस का इस्तेमाल करेगा. इसलिए, जब उपयोगकर्ता ऐक्सेस के अनुरोध का जवाब देता है, तो अनुरोध करने वाले डिवाइस को अपने-आप सूचना नहीं मिलती. इसलिए, अनुरोध करने वाले डिवाइस को Google के अनुमति देने वाले सर्वर से पूछना होगा कि उपयोगकर्ता ने अनुरोध का जवाब कब दिया.

अनुरोध करने वाले डिवाइस को तब तक पोलिंग अनुरोध भेजते रहना चाहिए, जब तक उसे ऐसा रिस्पॉन्स न मिल जाए जिससे पता चलता हो कि उपयोगकर्ता ने ऐक्सेस के अनुरोध का जवाब दिया है या दूसरे चरण में मिले device_code और user_code की समयसीमा खत्म हो गई हो. दूसरे चरण में दिखाया गया interval, अनुरोधों के बीच इंतज़ार करने के लिए, सेकंड में समय बताता है.

पोल के लिए एंडपॉइंट का यूआरएल https://oauth2.googleapis.com/token है. पोलिंग अनुरोध में ये पैरामीटर शामिल होते हैं:

उदाहरण

यहां दिया गया स्निपेट, अनुरोध का सैंपल दिखाता है:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=client_id&
client_secret=client_secret&
device_code=device_code&
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code

इस उदाहरण में, एक ही अनुरोध भेजने के लिए curl कमांड दिखाया गया है:

curl -d "client_id=client_id&client_secret=client_secret& \
         device_code=device_code& \
         grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code" \
         -H "Content-Type: application/x-www-form-urlencoded" \
         https://oauth2.googleapis.com/token

पांचवां चरण: उपयोगकर्ता, ऐक्सेस के अनुरोध का जवाब देता है

इस इमेज में ऐसा पेज दिखाया गया है जो उपयोगकर्ताओं को उस verification_url पर नेविगेट करने पर दिखता है जिसे आपने तीसरे चरण में दिखाया था:

user_code डालने के बाद, अगर उपयोगकर्ता पहले से लॉग इन नहीं है, तो उसे Google में लॉग इन करना होगा. इसके बाद, उपयोगकर्ता को सहमति वाली स्क्रीन दिखेगी, जो यहां दिखाई गई स्क्रीन जैसी होगी:

छठा चरण: पोल के अनुरोधों के जवाबों को मैनेज करना

Google का अनुमति देने वाला सर्वर, हर पोलिंग अनुरोध का जवाब इनमें से किसी एक के साथ देता है:

ऐक्सेस दिया गया

अगर उपयोगकर्ता ने सहमति वाली स्क्रीन पर Allow पर क्लिक करके, डिवाइस का ऐक्सेस दिया है, तो रिस्पॉन्स में ऐक्सेस टोकन और रीफ़्रेश टोकन शामिल होता है. टोकन की मदद से, आपके डिवाइस को उपयोगकर्ता की ओर से Google API ऐक्सेस करने की अनुमति मिलती है. (रिस्पॉन्स में मौजूद scope प्रॉपर्टी से यह तय होता है कि डिवाइस कौनसे एपीआई ऐक्सेस कर सकता है.)

इस मामले में, एपीआई रिस्पॉन्स में ये फ़ील्ड शामिल होते हैं:

यहां दिया गया स्निपेट, जवाब का एक सैंपल दिखाता है:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email",
  "token_type": "Bearer",
  "refresh_token": "1/xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

ऐक्सेस टोकन का लाइफ़टाइम सीमित होता है. अगर आपके ऐप्लिकेशन को लंबे समय तक किसी एपीआई का ऐक्सेस चाहिए, तो वह नया ऐक्सेस टोकन पाने के लिए रिफ़्रेश टोकन का इस्तेमाल कर सकता है. अगर आपके ऐप्लिकेशन को इस तरह के ऐक्सेस की ज़रूरत है, तो उसे बाद में इस्तेमाल करने के लिए रीफ़्रेश टोकन सेव करना चाहिए.

ऐक्सेस करने की मंज़ूरी नहीं मिली

अगर उपयोगकर्ता डिवाइस का ऐक्सेस देने से मना करता है, तो सर्वर के रिस्पॉन्स में 403 एचटीटीपी रिस्पॉन्स स्टेटस कोड (Forbidden) होता है. रिस्पॉन्स में यह गड़बड़ी होती है:

{
  "error": "access_denied",
  "error_description": "Forbidden"
}

अनुमति मिलना बाकी है

अगर उपयोगकर्ता ने अब तक अनुमति देने की प्रोसेस पूरी नहीं की है, तो सर्वर 428 एचटीटीपी रिस्पॉन्स स्टेटस कोड (Precondition Required) दिखाता है. रिस्पॉन्स में यह गड़बड़ी दिखती है:

{
  "error": "authorization_pending",
  "error_description": "Precondition Required"
}

बहुत ज़्यादा बार पोल करना

अगर डिवाइस, पोलिंग के अनुरोध बहुत बार भेजता है, तो सर्वर 403 एचटीटीपी रिस्पॉन्स स्टेटस कोड (Forbidden) दिखाता है. रिस्पॉन्स में यह गड़बड़ी शामिल होती है:

{
  "error": "slow_down",
  "error_description": "Forbidden"
}

दूसरी गड़बड़ियां

अगर पोलिंग अनुरोध में कोई ज़रूरी पैरामीटर मौजूद नहीं है या पैरामीटर की वैल्यू गलत है, तो अनुमति देने वाला सर्वर भी गड़बड़ियां दिखाता है. आम तौर पर, इन अनुरोधों में 400 (Bad Request) या 401 (Unauthorized) एचटीटीपी रिस्पॉन्स का स्टेटस कोड होता है. इनमें ये गड़बड़ियां शामिल हैं:

Google API को कॉल करना

जब आपके ऐप्लिकेशन को ऐक्सेस टोकन मिल जाता है, तो किसी उपयोगकर्ता खाते की ओर से Google API को कॉल करने के लिए, टोकन का इस्तेमाल किया जा सकता है. हालांकि, इसके लिए ज़रूरी है कि एपीआई को ऐक्सेस का ज़रूरी दायरा दिया गया हो. ऐसा करने के लिए, एपीआई के अनुरोध में ऐक्सेस टोकन शामिल करें. इसके लिए, access_token क्वेरी पैरामीटर या Authorization एचटीटीपी हेडर Bearer की वैल्यू शामिल करें. जब भी हो सके, एचटीटीपी हेडर का इस्तेमाल करें. ऐसा इसलिए, क्योंकि क्वेरी स्ट्रिंग, सर्वर लॉग में दिखती हैं. ज़्यादातर मामलों में, Google API के कॉल सेट अप करने के लिए, क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है. उदाहरण के लिए, YouTube Live Streaming API को कॉल करते समय.

ध्यान दें कि YouTube Live Streaming API, सेवा खाते के फ़्लो के साथ काम नहीं करता. किसी सेवा खाते को YouTube खाते से लिंक करने का कोई तरीका नहीं है. इसलिए, इस फ़्लो की मदद से अनुरोधों को अनुमति देने की कोशिश करने पर, NoLinkedYouTubeAccount गड़बड़ी का मैसेज दिखेगा.

OAuth 2.0 Playground पर जाकर, Google के सभी एपीआई आज़माए जा सकते हैं और उनके दायरे देखे जा सकते हैं.

एचटीटीपी GET के उदाहरण

Authorization: Bearer एचटीटीपी हेडर का इस्तेमाल करके, liveBroadcasts.list एंडपॉइंट (YouTube Live Streaming API) को कॉल करने का तरीका कुछ ऐसा दिख सकता है. ध्यान दें कि आपको अपना ऐक्सेस टोकन डालना होगा:

GET /youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

यहां पुष्टि किए गए उपयोगकर्ता के लिए, access_token क्वेरी स्ट्रिंग पैरामीटर का इस्तेमाल करके, उसी एपीआई को कॉल किया गया है:

GET https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

curl के उदाहरण

इन कमांड की जांच, curl कमांड-लाइन ऐप्लिकेशन की मदद से की जा सकती है. यहां एक उदाहरण दिया गया है, जिसमें एचटीटीपी हेडर के विकल्प का इस्तेमाल किया गया है. यह विकल्प इस्तेमाल करना सबसे सही है:

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/liveBroadcasts?part=id%2Csnippet&mine=true

इसके अलावा, क्वेरी स्ट्रिंग पैरामीटर का विकल्प भी चुना जा सकता है:

curl https://www.googleapis.com/youtube/v3/liveBroadcasts?access_token=access_token&part=id%2Csnippet&mine=true

ऐक्सेस टोकन रीफ़्रेश करना

ऐक्सेस टोकन समय-समय पर खत्म हो जाते हैं और किसी एपीआई अनुरोध के लिए अमान्य क्रेडेंशियल बन जाते हैं. अगर आपने टोकन से जुड़े स्कोप के लिए ऑफ़लाइन ऐक्सेस का अनुरोध किया है, तो उपयोगकर्ता से अनुमति लिए बिना ही ऐक्सेस टोकन को रीफ़्रेश किया जा सकता है. भले ही, उपयोगकर्ता मौजूद न हो.

ऐक्सेस टोकन को रीफ़्रेश करने के लिए, आपका ऐप्लिकेशन Google के ऑथराइज़ेशन सर्वर (https://oauth2.googleapis.com/token) को एचटीटीपीएस POST अनुरोध भेजता है. इस अनुरोध में ये पैरामीटर शामिल होते हैं:

यहां दिया गया स्निपेट, अनुरोध का सैंपल दिखाता है:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

जब तक उपयोगकर्ता ने ऐप्लिकेशन को दिया गया ऐक्सेस रद्द नहीं किया है, तब तक टोकन सर्वर एक JSON ऑब्जेक्ट दिखाता है. इसमें नया ऐक्सेस टोकन होता है. यहां दिया गया स्निपेट, रिस्पॉन्स का एक उदाहरण दिखाता है:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly https://www.googleapis.com/auth/calendar.readonly",
  "token_type": "Bearer"
}

ध्यान दें कि जारी किए जाने वाले रीफ़्रेश टोकन की संख्या सीमित होती है. हर क्लाइंट/उपयोगकर्ता के कॉम्बिनेशन के लिए एक सीमा और सभी क्लाइंट के लिए हर उपयोगकर्ता के लिए एक सीमा तय होती है. आपको रीफ़्रेश टोकन को लंबे समय तक स्टोर करने की सुविधा में सेव करना चाहिए. साथ ही, जब तक वे मान्य हैं, तब तक उनका इस्तेमाल करना जारी रखना चाहिए. अगर आपका ऐप्लिकेशन बहुत ज़्यादा रीफ़्रेश टोकन का अनुरोध करता है, तो हो सकता है कि वह इन सीमाओं तक पहुंच जाए. ऐसे में, पुराने रीफ़्रेश टोकन काम करना बंद कर देंगे.

टोकन रद्द करना

कुछ मामलों में, हो सकता है कि उपयोगकर्ता किसी ऐप्लिकेशन को दिया गया ऐक्सेस रद्द करना चाहे. उपयोगकर्ता, खाता सेटिंग पर जाकर, ऐक्सेस रद्द कर सकता है. ज़्यादा जानकारी के लिए, तीसरे पक्ष की ऐसी साइटों और ऐप्लिकेशन से साइट या ऐप्लिकेशन का ऐक्सेस हटाएं जिनके पास आपके खाते का ऐक्सेस है के सहायता दस्तावेज़ में, 'साइट या ऐप्लिकेशन का ऐक्सेस हटाएं' सेक्शन देखें.

यह भी मुमकिन है कि कोई ऐप्लिकेशन, प्रोग्राम के हिसाब से अपने लिए दिया गया ऐक्सेस रद्द कर दे. प्रोग्राम के ज़रिए अनुमति रद्द करना तब ज़रूरी होता है, जब कोई उपयोगकर्ता सदस्यता रद्द करता है, किसी ऐप्लिकेशन को हटाता है या किसी ऐप्लिकेशन के लिए ज़रूरी एपीआई संसाधनों में काफ़ी बदलाव होता है. दूसरे शब्दों में, ऐप्लिकेशन को हटाने की प्रोसेस में एपीआई अनुरोध शामिल हो सकता है. इससे यह पक्का किया जा सकता है कि ऐप्लिकेशन को पहले दी गई अनुमतियां हटा दी गई हैं.

प्रोग्राम के हिसाब से किसी टोकन को रद्द करने के लिए, आपका ऐप्लिकेशन https://oauth2.googleapis.com/revoke को अनुरोध भेजता है और टोकन को पैरामीटर के तौर पर शामिल करता है:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

टोकन, ऐक्सेस टोकन या रीफ़्रेश टोकन हो सकता है. अगर टोकन ऐक्सेस टोकन है और उससे जुड़ा कोई रीफ़्रेश टोकन है, तो रीफ़्रेश टोकन भी रद्द कर दिया जाएगा.

अगर रद्द करने की प्रोसेस पूरी हो जाती है, तो रिस्पॉन्स का एचटीटीपी स्टेटस कोड 200 होगा. गड़बड़ी की स्थितियों के लिए, गड़बड़ी के कोड के साथ एक एचटीटीपी स्टेटस कोड 400 दिखाया जाता है.

अनुमति वाले स्कोप

डिवाइसों के लिए OAuth 2.0 फ़्लो, सिर्फ़ इन स्कोप के लिए काम करता है: