प्रमाणीकरण

s.id API के साथ प्रमाणीकरण के दो तरीके, server-to-server के लिए API keys, उपयोगकर्ताओं की ओर से कार्य करने के लिए OAuth 2.0।

सर्वर-टू-सर्वर एक्सेस

API keys server-to-server integrations को authenticate करती हैं। Dashboard → Developer → API Keys में एक बनाएं, scopes चुनें और इसे Bearer token के रूप में पास करें।

दायरा	पहुँच
`links:read`	लिंक सूचीबद्ध और पढ़ें
`links:write`	लिंक बनाएँ और अपडेट करें (बनाना, संपादित करना, पुनर्स्थापित करना)
`links:archive`	लिंक संग्रहित करें
`links:analytics`	प्रति लिंक क्लिक आँकड़े और आजीवन संख्या पढ़ें
`qr:read`	QR कोड सेटिंग पढ़ें (ग्लोबल और प्रति लिंक)
`qr:write`	QR कोड सेटिंग कस्टमाइज़ करें (ग्लोबल और प्रति लिंक)
`user:read`	प्रमाणित उपयोगकर्ता प्रोफ़ाइल और अकाउंट कोटा पढ़ें
`microsites:read`	Microsite पढ़ें
`microsites:write`	Microsite कंपोनेंट बनाएँ, अपडेट करें और प्रबंधित करें
`microsites:delete`	Microsite और उनके कंपोनेंट हटाएँ

bash

Authorization: Bearer sk_live_...

bash

curl https://api.s.id/v2/links \
  -H "Authorization: Bearer sk_live_..."

Keys sk_live_ से शुरू होती हैं और creation के समय केवल एक बार दिखाई जाती हैं।
केवल वही minimum scopes मांगें जो आपके integration को चाहिए।
compromise होने पर keys तुरंत revoke करें, नई बनाएं।
Client-side (browsers, mobile apps) पर API keys कभी expose न करें।

Authorization flow

सहमति के लिए उपयोगकर्ता को s.id पर रीडायरेक्ट करें, callback state सत्यापित करें, फिर एक बार उपयोग होने वाले कोड को access token और घूमते refresh token से बदलें।

अप्रत्याशित state मान बनाएँ, उसे उपयोगकर्ता सेशन में रखें और CSRF रोकने के लिए callback पर सटीक मिलान सत्यापित करें।
ऐसा redirect_uri उपयोग करें जो आपके OAuth ऐप के लिए पंजीकृत मान से पूरी तरह मेल खाता हो।

PKCE आवश्यक, client secret नहीं

SPA, मोबाइल ऐप और CLI के लिए। रैंडम code_verifier बनाएँ, authorize पर उसका S256 challenge भेजें, फिर token exchange के दौरान मूल verifier भेजें।

bash

https://api.s.id/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&
  scope=links%3Aread%20links%3Awrite&
  state=RANDOM_CSRF_VALUE&
  code_challenge=BASE64URL_SHA256_VERIFIER&
  code_challenge_method=S256

bash

curl -X POST https://api.s.id/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=ORIGINAL_RANDOM_VERIFIER"

विश्वसनीय बैकएंड पर client secret

सर्वर-रेंडर या बैकएंड ऐप के लिए जो client_secret को गोपनीय रख सकते हैं। PKCE वैकल्पिक रहता है और अतिरिक्त सुरक्षा के लिए सुझाया जाता है।

bash

https://api.s.id/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&
  scope=links%3Aread%20links%3Awrite&
  state=RANDOM_CSRF_VALUE

bash

curl -X POST https://api.s.id/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://app.example.com/callback"

एक्सेस टोकन	विवरण
`access_token`	1 घंटे बाद समाप्त होता है
`refresh_token`	30 दिनों बाद समाप्त होता है
`code`	एक बार उपयोग; 10 मिनट बाद समाप्त

bash

curl -X POST https://api.s.id/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "refresh_token=CURRENT_REFRESH_TOKEN"

bash

curl -X POST https://api.s.id/oauth/revoke \
  -H "Content-Type: application/json" \
  -d '{"token":"TOKEN_TO_REVOKE"}'

डिस्कवरी और टोकन ऑपरेशन	विवरण
`https://api.s.id/.well-known/oauth-authorization-server`	RFC 8414 मेटाडेटा से endpoint URL, समर्थित स्कोप और PKCE विधियाँ खोजें।
`POST /oauth/introspect`	गोपनीय संसाधन सर्वर जाँच सकते हैं कि टोकन सक्रिय है या नहीं और उसके स्कोप देख सकते हैं।
`POST /oauth/revoke`	जब उपयोगकर्ता आपका इंटीग्रेशन डिस्कनेक्ट करे तब access token या refresh token रद्द करें।
`GET /oauth/userinfo`	user:read वाले OAuth एक्सेस टोकन से जुड़ी प्रोफ़ाइल पढ़ें।

Developer Dashboard खोलें