OAuth PKCE

OAuth PKCE

OAuth 2.0 PKCE (कोड एक्सचेंज के लिए प्रूफ कुंजी) सार्वजनिक क्लाइंट ऐप्स (ब्राउज़र एसपीए, मोबाइल ऐप्स) को लंबे समय तक चलने वाले सर्वर गुप्त क्लाइंट-साइड को संग्रहीत किए बिना व्यक्तिगत उपयोगकर्ताओं की ओर से API कॉल करने देता है।

OAuth PKCE का उपयोग कब करें

• एक ब्राउज़र SPA या मोबाइल ऐप बनाना जिसके लिए प्रति-उपयोगकर्ता बिलिंग की आवश्यकता हो
• मल्टी-टेनेंट SaaS - प्रत्येक अंतिम-उपयोगकर्ता अपने स्वयं के API उपयोग के लिए भुगतान करता है
• आप साझा गुप्त क्लाइंट-साइड (सार्वजनिक क्लाइंट) संग्रहीत नहीं कर सकते
• आपको एकल साझा API कुंजी के बजाय प्रति-उपयोगकर्ता अलग, रद्द की जा सकने वाली कुंजी चाहिए (जो उपयोगकर्ता द्वारा रद्द किए जाने तक मान्य रहती है)

आपके उपयोगकर्ता क्या देखेंगे

अपनी साइन-इन स्क्रीन पर इन चरणों का वर्णन करें:

1. आपके ऐप में वे "BazaarLink से साइन इन करें" चुनते हैं (या आप बटन का जो भी नाम रखें)।
2. उनका ब्राउज़र BazaarLink का ऑथराइज़ेशन पेज खोलता है। यदि वे अभी साइन इन नहीं हैं, तो पहले साइन इन करते हैं और अपने आप इस पेज पर लौट आते हैं।
3. पेज आपके ऐप का पता और अनुमति देने पर होने वाली बातें दिखाता है: ऐप के लिए एक नई API कुंजी बनती है, उपयोग का शुल्क उनके BazaarLink बैलेंस से कटता है, और वे कुंजी को किसी भी समय रद्द कर सकते हैं। वे कुंजी का नाम रख सकते हैं और मासिक खर्च सीमा तय कर सकते हैं (दोनों वैकल्पिक)।
4. वे "अनुमति दें" पर क्लिक करते हैं और आपके ऐप पर वापस भेज दिए जाते हैं। यदि वे "अस्वीकार करें" पर क्लिक करते हैं, तो कोई कुंजी नहीं बनती, आपके ऐप को सूचित नहीं किया जाता और उन्हें "एक्सेस अस्वीकृत" पेज दिखता है।
5. बाद में एक्सेस रद्द करने के लिए वे "API कुंजियाँ" पेज (https://bazaarlink.ai/keys) खोलते हैं और आपके ऐप के नाम वाली कुंजी को अक्षम या हटा देते हैं।

यह कैसे काम करता है

चरण 1 - प्रमाणीकरण आरंभ करें — एक यादृच्छिक कोड_सत्यापनकर्ता (एक लंबी यादृच्छिक स्ट्रिंग) और उसके SHA-256 हैश को कोड_चैलेंज के रूप में जेनरेट करें, फिर उपयोगकर्ता को BazaarLink प्रमाणीकरण पृष्ठ पर रीडायरेक्ट करें।

https://bazaarlink.ai/auth?callback_url=https://yourapp.com/callback&code_challenge=CODE_CHALLENGE&code_challenge_method=S256

ऑथराइज़ेशन URL के पैरामीटर

• callback_url (आवश्यक) — अनुमति देने के बाद उपयोगकर्ता जहाँ लौटता है। नियम नीचे देखें।
• code_challenge (आवश्यक) — आपके code_verifier का base64url-एन्कोडेड SHA-256 (43 अक्षर, बिना पैडिंग)।
• code_challenge_method (आवश्यक) — S256 होना चाहिए।
• state (वैकल्पिक) — आपका अपना अपारदर्शी CSRF मान, 1 से 256 प्रिंट करने योग्य ASCII अक्षर। BazaarLink इसे code के ठीक बाद &state=… के रूप में बिना बदले लौटा देता है। गलत प्रारूप वाला state होने पर प्राधिकरण पेज "अमान्य प्राधिकरण अनुरोध" दिखाता है।
• key_label (वैकल्पिक) — अधिकतम 100 अक्षर। यह सहमति पेज पर कुंजी का नाम पहले से भर देता है (उपयोगकर्ता इसे बदल सकता है)। बहुत लंबे या खाली लेबल अनदेखे कर दिए जाते हैं।
• Headless tools (CLI / desktop, no callback_url) — omit callback_url. After the user allows, the page shows a one-time code (valid 5 minutes, single use) for them to enter into your tool; exchange it exactly like a redirected code. The page cannot show which app is asking, so tell users to enter the code only in a tool they started themselves.

समर्थित नहीं

• workspace_id और required_workspace_id — समर्थित नहीं। कुंजी हमेशा उपयोगकर्ता के अपने खाते की होती है।
• code_challenge_method=plain — समर्थित नहीं (केवल S256)।

callback_url के नियम

• यह https:// होना चाहिए। http:// केवल localhost, 127.0.0.1 और [::1] (किसी भी पोर्ट) के लिए स्वीकार किया जाता है; तब सहमति पेज स्थानीय विकास की चेतावनी दिखाता है।
• कोई फ्रैगमेंट (#) नहीं, URL में उपयोगकर्ता नाम या पासवर्ड नहीं, अधिकतम 2048 अक्षर।
• सहमति पेज आपके callback का होस्ट नाम दिखाता है ताकि उपयोगकर्ता देख सके कि कौन सा ऐप अनुरोध कर रहा है।
• उपयोगकर्ता के अनुमति देने के बाद ब्राउज़र code=… जुड़े हुए आपके callback_url पर भेजा जाता है (और यदि आपने state भेजा था तो state=… भी; मौजूदा क्वेरी स्ट्रिंग बनी रहती है)। code 10 मिनट तक मान्य रहता है और केवल एक बार काम करता है।

चरण 2 - API कुंजी के लिए एक्सचेंज कोड — उपयोगकर्ता द्वारा अनुरोध को अधिकृत करने के बाद, BazaarLink एक बार उपयोग होने वाले code के साथ आपके callback_url पर रीडायरेक्ट करता है। code 10 मिनट तक मान्य रहता है और केवल एक बार उपयोग हो सकता है; गलत code_verifier से वह रद्द हो जाता है। उपयोगकर्ता की API कुंजी पाने के लिए code, code_verifier और code_challenge_method (तीनों आवश्यक) POST करें।

curl https://bazaarlink.ai/api/v1/auth/keys \
-H "Content-Type: application/json" \
-d '{
  "code": "<CODE_FROM_CALLBACK_URL>",
  "code_verifier": "<CODE_VERIFIER>",
  "code_challenge_method": "S256"
}'

# Response
# { "key": "sk-bl-...", "user_id": "..." }

चरण 3 - उपयोगकर्ता-स्कोप्ड कुंजी का उपयोग करें — लौटाई गई कुंजी एक सामान्य BazaarLink API कुंजी है जो अधिकृत करने वाले उपयोगकर्ता की है — उपयोग का शुल्क आपके नहीं, उस उपयोगकर्ता के बैलेंस से कटता है।

curl https://bazaarlink.ai/api/v1/chat/completions \
-H "Authorization: Bearer sk-bl-..." \
-H "Content-Type: application/json" \
-d '{"model": "google/gemini-3.5-flash", "messages": [{"role": "user", "content": "Hello"}]}'

JavaScript उदाहरण (ब्राउज़र)

// 1) Create a verifier + S256 challenge, then send the user to BazaarLink
const b64url = (buf) => btoa(String.fromCharCode(...new Uint8Array(buf)))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
const verifier = b64url(crypto.getRandomValues(new Uint8Array(32)));
const challenge = b64url(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier)));
sessionStorage.setItem("bl_verifier", verifier);
// "state" is optional: BazaarLink hands it back unchanged next to the code.
const state = b64url(crypto.getRandomValues(new Uint8Array(16)));
sessionStorage.setItem("bl_state", state);
location.href =
"https://bazaarlink.ai/auth?callback_url=" + encodeURIComponent(location.origin + "/callback") +
"&code_challenge=" + challenge + "&code_challenge_method=S256&state=" + state;

// 2) On /callback: check your own state, then exchange the one-time code for a user key
const params = new URLSearchParams(location.search);
if (params.get("state") !== sessionStorage.getItem("bl_state")) throw new Error("state mismatch");
const res = await fetch("https://bazaarlink.ai/api/v1/auth/keys", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
  code: params.get("code"),
  code_verifier: sessionStorage.getItem("bl_verifier"),
  code_challenge_method: "S256",
}),
});
if (!res.ok) throw new Error((await res.json()).error?.message ?? "exchange failed"); // 403 invalid_code: ask the user to authorize again
const { key } = await res.json(); // use as: Authorization: Bearer <key>

/auth पेज और POST /api/v1/auth/keys https://bazaarlink.ai से परोसे जाते हैं (api.bazaarlink.ai से नहीं)। मिली हुई कुंजी दोनों बेस URL पर काम करती है: https://bazaarlink.ai/api/v1 और https://api.bazaarlink.ai/v1।

यदि उपयोगकर्ता अधिकृत करते समय खर्च सीमा तय करता है, तो वह मासिक सीमा होती है और खाते की मासिक अवधि के साथ रीसेट होती है।

त्रुटियाँ

त्रुटियाँ OpenAI-शैली के प्रारूप {"error":{"message","type","code"}} में आती हैं। POST /api/v1/auth/keys ये लौटा सकता है:

• 400 invalid_code_challenge_method — code_challenge_method अनुपस्थित है, plain है, या S256 के अलावा कुछ और है।
• 400 — JSON बॉडी अमान्य है, या code / code_verifier अनुपस्थित है।
• 403 invalid_code — code अज्ञात, समाप्त या पहले ही उपयोग किया हुआ है, code_verifier गलत है, या खाते को अब अनुमति नहीं है। इन सभी में जानबूझकर एक ही संदेश लौटाया जाता है, ताकि कॉल करने वाला इन्हें अलग न पहचान सके। गलत code_verifier भी code को रद्द कर देता है: उपयोगकर्ता से दोबारा अधिकृत करने को कहें।
• 429 rate_limited — एक IP से 10 मिनट में 30 से अधिक एक्सचेंज प्रयास (Retry-After हेडर देखें)।
• 429 key_total_cap — खाते के पास पहले से अधिकतम 200 API कुंजियाँ हैं।
• 405 — केवल POST स्वीकार किया जाता है।

अपने सर्वर से कोड बनाएँ (प्रबंधन कुंजी)

व्यक्तिगत प्रबंधन कुंजी (Management Key) का स्वामी उपयोगकर्ता को ब्राउज़र पेज पर भेजे बिना सीधे POST /api/v1/auth/keys/code से प्रमाणीकरण कोड बना सकता है (OpenRouter-संगत)। कोड प्रबंधन कुंजी के स्वामी से जुड़ा होता है, इसलिए इसके बदले मिलने वाली कुंजी उसी स्वामी के खाते की मानक कुंजी होती है, जिसकी सीमा, अवधि, समाप्ति और नाम यहीं तय किए जाते हैं। इसका उपयोग तब करें जब आपके अपने टूल के पास पहले से प्रबंधन कुंजी हो और वह किसी ऐप को सीमित कुंजी देना चाहता हो। एक्सचेंज (POST /api/v1/auth/keys) ऊपर जैसा ही है।

• callback_url (आवश्यक) और code_challenge + code_challenge_method=S256 (आवश्यक) — नियम प्रमाणीकरण URL जैसे ही हैं।
• key_label (वैकल्पिक) — अधिकतम 100 अक्षर; कुंजी का नाम। डिफ़ॉल्ट: "App: <आपका callback होस्ट>"।
• limit (वैकल्पिक) — USD में खर्च सीमा, 0 या अधिक; 0 या न देने का मतलब कोई सीमा नहीं।
• usage_limit_type (वैकल्पिक) — daily, weekly या monthly: सीमा कितनी बार रीसेट होती है। केवल limit के साथ उपयोग होता है; डिफ़ॉल्ट monthly है।
• expires_at (वैकल्पिक) — कुंजी कब समाप्त होगी: भविष्य का ISO 8601 UTC समय, सेकंड सहित, जैसे 2026-12-31T23:59:59Z। केवल मिनट तक के मान अस्वीकार किए जाते हैं। न देने पर कुंजी रद्द किए जाने तक मान्य रहती है।
• workspace_id — समर्थित नहीं (400)। spawn_agent और spawn_cloud स्वीकार किए जाते हैं पर अनदेखे रहते हैं।

curl https://bazaarlink.ai/api/v1/auth/keys/code \
-H "Authorization: Bearer sk-bl-YOUR_MGMT_KEY" \
-H "Content-Type: application/json" \
-d '{
  "callback_url": "https://yourapp.com/callback",
  "code_challenge": "<CODE_CHALLENGE>",
  "code_challenge_method": "S256",
  "key_label": "My app",
  "limit": 10,
  "usage_limit_type": "monthly",
  "expires_at": "2026-12-31T23:59:59Z"
}'

# Response
# { "data": { "id": "<ONE_TIME_CODE>", "app_id": 123456789, "created_at": "2026-10-22T12:00:00.000Z" } }
# Then POST { "code": "<ONE_TIME_CODE>", "code_verifier": "<CODE_VERIFIER>", "code_challenge_method": "S256" } to /api/v1/auth/keys

प्रतिक्रिया: { "data": { "id", "app_id", "created_at" } }। id वह एक-बार उपयोग वाला कोड है जिसे एक्सचेंज करना है (10 मिनट तक मान्य, केवल एक बार)। BazaarLink में ऐप रजिस्ट्री नहीं है, इसलिए app_id आपके callback पते से निकाला गया स्थिर पूर्णांक है: एक ही पते को हमेशा वही app_id मिलता है।

• 401 unauthorized — Bearer कुंजी नहीं दी गई, या कुंजी अज्ञात है।
• 403 management_key_required — कुंजी व्यक्तिगत प्रबंधन कुंजी नहीं है (मानक कुंजियाँ और संगठन की प्रबंधन कुंजियाँ अस्वीकार की जाती हैं)।
• 403 account_not_allowed — कुंजी का स्वामी निलंबित या हटाया गया है।
• 400 — invalid_callback_url, invalid_code_challenge_method, invalid_code_challenge, invalid_expires_at, workspace_not_supported, या गलत बॉडी।
• 429 rate_limited — एक स्वामी के लिए प्रति घंटे 30 से अधिक कोड, या एक IP से प्रति घंटे 120 से अधिक (Retry-After देखें)।

आपको मिलने वाली कुंजी

• एक मानक BazaarLink API कुंजी (sk-bl-…), ठीक वैसी ही जैसी "API कुंजियाँ" पेज पर बनाई गई कुंजी होती है। यह उपयोगकर्ता द्वारा रद्द किए जाने तक मान्य रहती है।
• उपयोग का शुल्क उपयोगकर्ता के BazaarLink बैलेंस से कटता है। यदि उपयोगकर्ता ने सहमति पेज पर खर्च सीमा तय की है, तो वह मासिक सीमा है।
• यह दोनों बेस URL पर काम करती है: https://bazaarlink.ai/api/v1 और https://api.bazaarlink.ai/v1।
• यह खाते की 200 कुंजियों की सीमा में गिनी जाती है और उपयोगकर्ता की "API कुंजियाँ" सूची में दिखती है, जहाँ वह इसे किसी भी समय अक्षम या हटा सकता है।
• निलंबित या हटाए गए खाते ऐप को अधिकृत नहीं कर सकते, और निलंबन से पहले जारी किया गया code एक्सचेंज के समय अस्वीकार कर दिया जाता है (403 invalid_code)।

आपको क्या मिलता है

• प्राधिकरण कोड + PKCE प्रवाह
• प्रति-उपयोगकर्ता बिलिंग: प्रत्येक उपयोगकर्ता अपने बैलेंस से अपने उपयोग का भुगतान करता है
• प्रत्येक उपयोगकर्ता के लिए अलग कुंजी, जो उपयोगकर्ता के "API कुंजियाँ" पेज पर सूचीबद्ध होती है और जिसे वह रद्द कर सकता है