# प्रमाणीकरण और OAuth

> API कुंजियाँ, PKCE के साथ OAuth 2.1 (SMART on FHIR स्टैंडअलोन लॉन्च), OpenID Connect id_token, SMART v2 रोगी स्कोप, टोकन जीवनकाल और सहमति जीवनचक्र।

Source: https://developers.anpheros.com/hi/guides/authentication

Anpheros Platform तीन प्रकार के क्रेडेंशियल्स स्वीकार करता है। प्रत्येक अनुरोध में ठीक एक होता है।

| क्रेडेंशियल | कैसा दिखता है | कौन | देखता है |
|---|---|---|---|
| API कुंजी | `sk_test_…` (सैंडबॉक्स) / `sk_live_…` (उत्पादन) | एक प्रोजेक्ट का सर्वर | वे रोगी जिन्हें प्रोजेक्ट ने बनाया है (सैंडबॉक्स में, जिसमें 30 सिंथेटिक रोगियों की अपनी प्रतिलिपि भी शामिल है) |
| OAuth एक्सेस टोकन | `at_…` | सहमति के तहत एक रोगी के लिए कार्य करने वाला एक एप्लिकेशन | केवल वह रोगी, प्रदान किए गए SMART स्कोप के भीतर |
| Firebase ID टोकन | JWT | डैशबोर्ड में एक डेवलपर, या "कनेक्शन" में एक रोगी | उनके अपने संगठन / उनके अपने रिकॉर्ड |

इसे `Authorization: Bearer <credential>` के रूप में भेजें (API कुंजियाँ `X-Api-Key` के रूप में भी काम करती हैं)।

## एपीआई कुंजियाँ (API Keys)
- डैशबोर्ड में या `POST /admin/projects/{id}/keys` के माध्यम से बनाई जाती हैं; एक बार दिखाई जाती हैं; SHA-256 हैश के रूप में संग्रहीत की जाती हैं।
- स्कोप (Scopes): `read`, `write`। एक कुंजी कभी भी अपने प्रोजेक्ट के वातावरण को पार नहीं करती (`sk_test_` उत्पादन डेटा तक नहीं पहुँच सकता और इसके विपरीत)।
- प्रति-कुंजी दर सीमा (डिफ़ॉल्ट 600/मिनट) प्लेटफ़ॉर्म-व्यापी (साझा स्टोर) लागू की जाती है, जिसमें 429 पर `Retry-After` होता है। प्रति-आईपी सीमा 600/मिनट भी है।
- राइट्स पर वैकल्पिक हेडर (Optional headers on writes): `X-Anpheros-Author-Type`, `X-Anpheros-Author-Ref`, `X-Anpheros-Source-System`, `X-Anpheros-Origin-Id`, `X-Anpheros-Acting-As` (आपके **अपने डायरेक्टरी** का एक Practitioner/PractitionerRole), `X-Anpheros-On-Behalf-Of` (आपके अपने डायरेक्टरी का एक Organization)। ये Provenance को पॉप्युलेट करते हैं।

## OAuth 2.1 (SMART on FHIR, standalone launch)
Discovery: `GET /.well-known/smart-configuration`.

1. `GET /oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=…&state=…&code_challenge=…&code_challenge_method=S256[&purpose=treatment][&patient=<pairwise id>][&lang=ro]`
   होस्टेड सहमति पृष्ठ दिखाता है। PKCE S256 अनिवार्य है; `redirect_uri` को बिल्कुल पंजीकृत होना चाहिए।
2. रोगी साइन इन करता है (Firebase के माध्यम से Google या ईमेल), रिकॉर्ड (अपना या आश्रित का) चुनता है, अवधि (30/90/180/365 दिन) और अनुमति देता है। प्लेटफ़ॉर्म एक बार का कोड जारी करता है (10 मिनट)।
3. `POST /oauth/token` के साथ `grant_type=authorization_code&code=…&code_verifier=…&redirect_uri=…&client_id=…` (गोपनीय क्लाइंट `client_secret` जोड़ते हैं)।
   प्रतिक्रिया: `access_token` (30 मिनट), `refresh_token` (30 दिन, रोटेटिंग), `patient` (रिकॉर्ड के लिए आपका जोड़ीदार आईडी), `grant_id`, `scope`।
4. रीफ़्रेश: `grant_type=refresh_token`। प्रत्येक रीफ़्रेश टोकन एकल-उपयोग है। **उपयोग किए गए रीफ़्रेश टोकन को प्रस्तुत करने से पूरी श्रृंखला रद्द हो जाती है** (चोरी का पता लगाना)। रीफ़्रेश अनुरोध की एक समानांतर डुप्लिकेट को अस्वीकार कर दिया जाता है और यह श्रृंखला को भी रद्द कर सकता है, इसलिए समवर्ती रूप से कभी भी रोटेट न करें।
5. रद्द करें: `POST /oauth/revoke` (टोकन + client_id)। रीफ़्रेश टोकन को रद्द करने से उसके एक्सेस टोकन भी रद्द हो जाते हैं।

टोकन प्रतिक्रियाओं में `Cache-Control: no-store` और `Pragma: no-cache` होते हैं, जैसा कि SMART की आवश्यकता है।

### OpenID Connect (`openid fhirUser`)
रोगी स्कोप के साथ `openid fhirUser` के लिए पूछें और टोकन प्रतिक्रिया में एक `id_token` भी शामिल होता है: RS256 के साथ हस्ताक्षरित एक JWT, जिसमें `iss` (प्लेटफ़ॉर्म का बेस URL), `sub` (व्यक्ति के लिए आपका जोड़ीदार आईडी), `aud` (आपका `client_id`), `exp`, `iat` और `fhirUser` — व्यक्ति के Patient संसाधन का पूर्ण URL, जिसे आपके द्वारा अभी प्राप्त एक्सेस टोकन से पढ़ा जा सकता है। Discovery `GET /.well-known/openid-configuration` पर है; सार्वजनिक कुंजियाँ `GET /oauth/jwks` पर हैं (टोकन हेडर में `kid`)। `nonce` पैरामीटर अभी समर्थित नहीं है (यह प्राधिकरण-कोड प्रवाह में वैकल्पिक है)। `launch/patient` और `offline_access` स्वीकार किए जाते हैं; टोकन प्रतिक्रिया का `patient` फ़ील्ड लॉन्च संदर्भ है।

अन्य अनुदान प्रकार: `client_credentials` (गोपनीय क्लाइंट; API कुंजी की तरह व्यवहार करता है), और प्रथम-पक्ष पहचान अनुदान (केवल विश्वसनीय क्लाइंट)।

### आपकी ब्रांडिंग सहमति पृष्ठ पर

एक एप्लिकेशन होस्टेड सहमति पृष्ठ पर अपना लोगो और एक्सेंट रंग दिखा सकता है। उन्हें कंसोल में सेट करें
(एप्लिकेशन → ब्रांड) या एडमिन API के साथ:

```http
PUT /admin/applications/{application_id}/branding
{"logo": "data:image/png;base64,…", "brand_color": "#1D4ED8"}
```

- **लोगो:** एक PNG, JPEG या WebP छवि डेटा URI के रूप में, 64 KB तक। सामग्री की जाँच की जाती है, घोषित प्रकार की नहीं;
  SVG स्वीकार नहीं किया जाता है। छवि एप्लिकेशन के साथ संग्रहीत की जाती है और पृष्ठ में एम्बेड की जाती है, इसलिए सहमति पृष्ठ
  आपके सर्वर पर कोई अनुरोध नहीं करता है।
- **एक्सेंट रंग:** `#RRGGBB`, प्राथमिक बटन के लिए उपयोग किया जाता है। इस पर सफ़ेद टेक्स्ट को कम से कम 4.5:1 (WCAG AA) का कंट्रास्ट बनाए रखना चाहिए; हल्के रंगों को अस्वीकार कर दिया जाता है।
- एक फ़ील्ड जिसे आप छोड़ देते हैं वह वैसा ही रहता है; `null` या एक खाली स्ट्रिंग इसे हटा देती है।

पृष्ठ का बाकी हिस्सा नहीं बदलता है: "Secured by Anpheros Platform" लाइन, एप्लिकेशन जो मांग रहा है उसकी सादे भाषा की सूची, और सैंडबॉक्स परियोजनाओं पर TEST बैनर बने रहते हैं, ताकि लोग हमेशा बता सकें कि सहमति Anpheros द्वारा रखी गई है। AI कनेक्टर (MCP) हमेशा एप्लिकेशन ब्रांडिंग के बिना Anpheros पृष्ठ दिखाते हैं।

### स्कोप
SMART v2 रोगी स्कोप: `patient/<Type>.<cruds>` एक वैकल्पिक `?category=<code>` फ़िल्टर के साथ (एकमात्र फ़िल्टर जिसे सर्वर लागू करता है; प्राधिकरण समय पर किसी भी अन्य फ़िल्टर को अस्वीकार कर दिया जाता है)। `patient/*.rs` सब कुछ पढ़ता है; `offline_access` एक रीफ़्रेश टोकन जोड़ता है। रोगी जनसांख्यिकी और निर्देशिका हमेशा अनुदान के तहत पठनीय होती हैं। अनुदान के बाहर एक संसाधन प्रकार 403 लौटाता है; अनुदान के बाहर एक रोगी 404 लौटाता है।

### सहमति जीवनचक्र
सहमति स्वचालित रूप से समाप्त हो जाती है, रोगी द्वारा किसी भी समय रद्द की जा सकती है (कनेक्शन स्क्रीन / `/me`), और एक सहमति के तहत हर रीड को एप्लिकेशन आईडी के साथ लॉग किया जाता है। Webhooks `consent.granted` / `consent.revoked` प्रोजेक्ट को सूचित करते हैं।

## त्रुटियाँ
401 अज्ञात/समाप्त क्रेडेंशियल · 403 क्रेडेंशियल मौजूद है लेकिन यह कार्य नहीं कर सकता · 404 संसाधन *आपके लिए* मौजूद नहीं है · 429 दर सीमित (`Retry-After`)। [`errors.md`](https://developers.anpheros.com/hi/guides/errors) देखें।