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

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

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 को कॉल करने वाले किसी भी ऐप्लिकेशन को, API Consoleमें उन एपीआई को चालू करना होगा.

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

1. Open the API Library में Google API Console.
2. If prompted, select a project, or create a new one.
3. YouTube Data API को ढूंढने और चालू करने के लिए, लाइब्रेरी पेज का इस्तेमाल करें. उन अन्य एपीआई का पता लगाएं जिनका इस्तेमाल आपका ऐप्लिकेशन करेगा. साथ ही, उन्हें भी चालू करें.

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

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

1. Go to the Credentials page.
2. क्लाइंट बनाएं पर क्लिक करें.
3. टीवी और सीमित इनपुट डिवाइस ऐप्लिकेशन का टाइप चुनें.
4. अपने OAuth 2.0 क्लाइंट को कोई नाम दें और बनाएं पर क्लिक करें.

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

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

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

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

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

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

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

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

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

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

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

इस चरण में, आपका डिवाइस Google के अनुमति देने वाले सर्वर https://oauth2.googleapis.com/device/code पर एक एचटीटीपी पोस्ट अनुरोध भेजता है. इससे आपके ऐप्लिकेशन की पहचान होती है. साथ ही, यह भी पता चलता है कि आपका ऐप्लिकेशन, उपयोगकर्ता की ओर से किन ऐक्सेस स्कोप को ऐक्सेस करना चाहता है. आपको इस यूआरएल को खोज से जुड़े दस्तावेज़ से पाना चाहिए. इसके लिए, 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 को ऐसे फ़ील्ड में दिखाया जाना चाहिए जिसमें 'W' साइज़ के 15 वर्ण शामिल किए जा सकते हों. दूसरे शब्दों में कहें, तो अगर कोड 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 APIs को कॉल करने के लिए क्लाइंट लाइब्रेरी का इस्तेमाल किया जा सकता है. उदाहरण के लिए, 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 फ़्लो, सिर्फ़ इन स्कोप के लिए काम करता है:

समय के हिसाब से ऐक्सेस

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

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