प्रमाणीकरण और API Keys

Discuse API हर अनुरोध को API key से प्रमाणित करता है। इसे X-API-Key request header में भेजें (या JSON body में api_key field के रूप में)। Keys disc_ prefix से शुरू होती हैं, एक ही project से जुड़ी होती हैं, और बनाते समय केवल एक बार पूरी दिखाई जाती हैं। यह guide बताती है कि इन्हें कैसे प्राप्त करें, इस्तेमाल करें, सुरक्षित रखें और rotate करें।

Discuse authentication कैसे काम करता है?

हर API call में एक valid API key शामिल होनी चाहिए। Discuse इसका उपयोग इन कामों के लिए करता है:

• आपके project के quota के हिसाब से usage track करना
• दुरुपयोग रोकने के लिए per-key rate limiting लागू करना
• Requests को सही project और उसकी settings से जोड़ना
• आपके account के resources तक access नियंत्रित करना

अपनी API Key प्राप्त करना

Step 1: Account बनाएँ

अगर आपने अभी तक नहीं किया है, तो discuse.com पर Discuse account के लिए sign up करें। आप free Basic plan से शुरुआत कर सकते हैं, जिसमें API requests का monthly allowance और text, spam, language, और image checks तक access शामिल है। हर plan की मौजूदा limits के लिए pricing page देखें।

Step 2: Dashboard पर जाएँ

Log in करने के बाद, अपने dashboard पर जाएँ। Navigation menu में "API Keys" या "Developer" section देखें।

Step 3: नई Key Generate करें

"Create New API Key" पर click करें और चाहें तो key के लिए कोई name या description दें। अगर आप कई keys बनाते हैं, तो इससे आपको हर key का purpose पहचानने में मदद मिलती है।

आपकी नई API key केवल एक बार दिखाई जाएगी। इसे तुरंत copy करें और सुरक्षित रूप से store करें - आप पूरी key फिर से नहीं देख पाएँगे।

अपनी API Key का उपयोग करना

हर request के X-API-Key header में अपनी API key शामिल करें:

curl -X POST https://api.discuse.com/api/v2/check \
  -H "Content-Type: application/json" \
  -H "X-API-Key: disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345" \
  -d '{
    "content": {
      "text": "Content to analyze"
    }
  }'

आप header के बजाय JSON body के अंदर api_key field के रूप में भी key भेज सकते हैं — header को प्राथमिकता दी जाती है ताकि key कभी भी request-body logs में न पहुँचे।

JavaScript उदाहरण

const response = await fetch('https://api.discuse.com/api/v2/check', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.DISCUSE_API_KEY
  },
  body: JSON.stringify({
    content: { text: 'Content to analyze' }
  })
});

Python उदाहरण

import requests
import os

response = requests.post(
    'https://api.discuse.com/api/v2/check',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['DISCUSE_API_KEY']
    },
    json={
        'content': {'text': 'Content to analyze'}
    }
)

API Key Security की Best Practices

Client-Side Code में Keys कभी expose न करें

API keys को browser में चलने वाले JavaScript में कभी भी शामिल नहीं करना चाहिए। Client-side code उन सभी को दिखाई देता है जो आपके page source को देखते हैं।

// WRONG - Don't do this!
const API_KEY = 'disc_aB3dEf6...'; // Exposed in browser

// CORRECT - Use a backend proxy
const response = await fetch('/api/moderate', {
  method: 'POST',
  body: JSON.stringify({ text: userInput })
});

Environment Variables का उपयोग करें

API keys को अपने codebase में नहीं, बल्कि environment variables में store करें:

# .env file (add to .gitignore!)
DISCUSE_API_KEY=disc_aB3dEf6GhIjKlMnOpQrStUvWxYz012345

// Access in Node.js
const apiKey = process.env.DISCUSE_API_KEY;

Keys को नियमित रूप से Rotate करें

अपनी API keys को समय-समय पर rotate करें, खासकर अगर आपको संदेह हो कि वे compromise हो गई हैं:

1. नई API key generate करें
2. नई key इस्तेमाल करने के लिए अपनी application update करें
3. Verify करें कि सब कुछ सही ढंग से काम कर रहा है
4. पुरानी key revoke करें

Note: revoked key लगभग 5 minutes तक usable रह सकती है क्योंकि validated keys cached होती हैं। Instant cutover की अपेक्षा करने के बजाय उस छोटे overlap को ध्यान में रखकर rotations plan करें।

अलग-अलग Environments के लिए अलग Keys इस्तेमाल करें

Development, staging, और production के लिए अलग-अलग API keys बनाएँ:

Environment	Key Purpose
Development	Testing और local development
Staging	Pre-production testing
Production	Live application traffic

इससे आप अन्य environments को प्रभावित किए बिना compromised key revoke कर सकते हैं।

Rate limiting कैसे काम करती है?

Rate limiting per API key होती है, per plan नहीं। हर key की requests-per-minute (RPM) limit key बनाते समय set की जाती है; अगर आप कोई limit specify नहीं करते, तो default 60 requests per minute होता है। एक ही account पर अलग-अलग keys की limits अलग हो सकती हैं, इसलिए आप high-throughput service को one-off integration की तुलना में higher RPM दे सकते हैं।

जब कोई key अपनी RPM limit से आगे निकल जाती है, तो request HTTP 429 Too Many Requests status के साथ fail होती है, जिसके message में बताया जाता है कि rate limit exceeded हो गई है। Rate-limit counters rolling one-minute window पर reset होते हैं।

Rate limits को handle करना

429 (और transient 5xx) पर back off करें और retry करें। क्योंकि window एक minute की है, लगभग एक second से शुरू होकर बढ़ने वाला exponential backoff अच्छी तरह काम करता है:

async function checkWithRetry(content, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch('https://api.discuse.com/api/v2/check', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': process.env.DISCUSE_API_KEY
      },
      body: JSON.stringify({ content })
    });

    if (response.status === 429 || response.status >= 500) {
      const delay = 1000 * Math.pow(2, attempt); // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response.json();
  }
  throw new Error('Max retries exceeded');
}

मुझे कौन-से error responses मिल सकते हैं?

स्थिति	HTTP status
Malformed request (empty content, text over 10,000 chars, too many URLs)	400 request validation
Missing or invalid API key	401
Key के लिए rate limit exceeded	429
Billing-period quota exhausted	200 with a message and usage (not an error status)

Quota exhaustion जानबूझकर HTTP error नहीं है: /api/v2/check response फिर भी 200 return करता है, जिसमें has_violations: false, exhausted quota का वर्णन करने वाला message, और api_requests_remaining: 0 दिखाने वाला usage object होता है। Status code पर निर्भर रहने के बजाय इन fields को inspect करें। Authentication failures 401, rate limits 429, और request-validation failures 400 return करते हैं। पूरी list के लिए Error और Response Codes reference देखें।

Multiple Keys को Manage करना

बड़ी teams या complex applications के लिए, आपको कई API keys की आवश्यकता हो सकती है:

Multiple Keys के Use Cases

1. Per-environment keys: Dev, staging, और production के लिए अलग keys
2. Per-service keys: अलग-अलग microservices के लिए अलग keys
3. Per-team keys: Internal billing के लिए team के अनुसार usage isolate करें
4. Temporary keys: Contractors या integrations के लिए short-lived keys

Key Management की Best Practices

• Keys को descriptive names दें: "Production - User Service", "Staging - Backend"
• Key usage document करें: कौन-सी key कहाँ इस्तेमाल हो रही है, इसका record बनाए रखें
• Alerts set up करें: Unusual usage patterns के लिए monitor करें
• Regular audits करें: Unused keys को quarterly review और clean up करें

अगले कदम

• Quick Start Guide - अपनी पहली API call करें
• Text Analysis - Sentiment detection के बारे में जानें
• Scaling Content Moderation - High-volume implementation patterns