प्रमाणीकरण

Markdown

यह गाइड आपको Human Dashboard के साथ प्रमाणीकरण करने और वह x-unico-accesskey जनरेट करने की प्रक्रिया बताती है, जिसका उपयोग आप सभी Human Token API अनुरोधों में करेंगे।

इस फ़्लो के दो चरण हैं:

प्रमाणीकरण करें — लॉगिन पूरा करें और एक्सेस टोकन प्राप्त करें। प्रमाणीकरण के दो तरीके उपलब्ध हैं:
- बायोमेट्रिक लॉगिन — Unico SDK के माध्यम से चेहरे का कैप्चर (signup और signin दोनों के लिए उपलब्ध)
- ईमेल OTP लॉगिन — पंजीकृत ईमेल पते पर भेजा गया एक बार उपयोग होने वाला कोड (केवल signin)
अपना संगठन सेट अप करें — अपनी कंपनी की प्रोफ़ाइल बनाएं और एक एक्सेस कुंजी जनरेट करें (केवल पहली बार signup पर)

अपने क्रेडेंशियल सेट अप करने के दो तरीके

इस गाइड में बताया गया सब कुछ Human Dashboard के माध्यम से भी किया जा सकता है, dashboard.unico.app पर — किसी API कॉल की आवश्यकता नहीं है।

विकल्प	कब उपयोग करें
Dashboard	पहली बार सेटअप, मैन्युअल कुंजी रोटेशन, कभी-कभार प्रबंधन
API	स्वचालित प्रोविज़निंग, CI/CD पाइपलाइन, प्रोग्रामेटिक कुंजी प्रबंधन

Dashboard का उपयोग करना

dashboard.unico.app पर जाएं
साइन अप या साइन इन करें — बायोमेट्रिक लॉगिन (चेहरे का कैप्चर) या ईमेल OTP का उपयोग करें
अपना संगठन बनाएं — अपनी कंपनी का नाम, देश और अनुमत डोमेन भरें
एक एक्सेस कुंजी जनरेट करें — Access Keys पर जाएं और Create key पर क्लिक करें; इसे तुरंत कॉपी करें, यह केवल एक बार दिखाई जाती है
ब्रांच प्रबंधित करें — Branches के अंतर्गत ब्रांच बनाएं और कॉन्फ़िगर करें; प्रत्येक ब्रांच अपनी स्वयं की एक्सेस कुंजी जनरेट करती है

Dashboard से मिलने वाली एक्सेस कुंजी वही x-unico-accesskey है जो सभी API अनुरोधों में उपयोग होती है — दोनों तरीके पूरी तरह से विनिमेय हैं।

बेस URL

इस पेज के सभी endpoint Human Dashboard API द्वारा प्रदान किए जाते हैं। Human Token API अनुरोध, जैसे Create Process और Get Process, एनवायरनमेंट में सूचीबद्ध API होस्ट पर जाते हैं।

एनवायरनमेंट	API	बेस URL
प्रोडक्शन	Human Dashboard API (लॉगिन, संगठन, एक्सेस कुंजियाँ और ब्रांच)	`https://api.humantoken.unico.app`

प्रमाणीकरण के तरीके

प्रमाणीकरण करने और authToken प्राप्त करने के लिए दो तरीके उपलब्ध हैं:

तरीका	Endpoint	कब उपयोग करें
बायोमेट्रिक	`POST /api/console/v1/auth/biometric/sessions`	Signup (नया अकाउंट) या Signin (लौटकर आया यूज़र)
ईमेल OTP	`POST /api/console/v1/auth/email/sessions`	केवल Signin — अकाउंट पहले से मौजूद होना चाहिए

बायोमेट्रिक लॉगिन intent

POST /api/console/v1/auth/biometric/sessions की प्रत्येक कॉल में एक intent घोषित करना ज़रूरी है:

`intent`	कब उपयोग करें	`email` फ़ील्ड	`name` फ़ील्ड
`LOGIN_INTENT_SIGNUP`	पहली बार पंजीकरण — नया अकाउंट बनाना	आवश्यक	आवश्यक
`LOGIN_INTENT_SIGNIN`	लौटकर आया यूज़र — अकाउंट पहले से मौजूद है	उपयोग नहीं होता	उपयोग नहीं होता
(छोड़ा गया)	`LOGIN_INTENT_SIGNIN` माना जाता है	उपयोग नहीं होता	उपयोग नहीं होता

intent, सेशन को पोल करते समय (स्टेप 2) होने वाले सत्यापन को नियंत्रित करता है:

SIGNUP — अगर वह बायोमेट्रिक पहचान पहले से पंजीकृत है, तो लॉगिन अस्वीकार कर देता है (डुप्लिकेट अकाउंट रोकता है)।
SIGNIN — अगर वह बायोमेट्रिक पहचान पंजीकृत नहीं है, तो लॉगिन अस्वीकार कर देता है (लॉग इन करने के लिए अकाउंट मौजूद होना चाहिए)।

चरण 1 — प्रमाणीकरण करें

स्टेप 1: बायोमेट्रिक लॉगिन सेशन शुरू करें

SIGNUP (पहली बार पंजीकरण)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNUP",
    "email": "[email protected]",
    "name": "Jane Doe"
  }'

ईमेल की विशिष्टता

अगर उस ईमेल से कोई अकाउंट पहले से पंजीकृत है, तो अनुरोध 400 Bad Request लौटाता है।

रिस्पॉन्स:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "",
    "token": ""
  }
}

SIGNUP के लिए, रिस्पॉन्स में link और token फ़ील्ड खाली होते हैं — बायोमेट्रिक कैप्चर लिंक दिए गए ईमेल पते पर भेजा जाता है।

SIGNIN (लौटकर आया यूज़र)

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "LOGIN_INTENT_SIGNIN"
  }'

रिस्पॉन्स:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "link": "https://humantoken.unico.io/...",
    "token": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

sessionId सहेजें।

SIGNUP: बायोमेट्रिक कैप्चर लिंक स्टेप 1 में दिए गए ईमेल पर भेजा जाता है। यूज़र से अपना इनबॉक्स देखने और कैप्चर पूरा करने के लिए कहें।
SIGNIN: अपने ब्राउज़र में link खोलें और बायोमेट्रिक कैप्चर पूरा करें।

स्टेप 2: सेशन के हल होने तक पोल करें

curl https://api.humantoken.unico.app/api/console/v1/auth/biometric/sessions/b3f1a2c4-0000-0000-0000-abcdef012345

हर 2–3 सेकंड में तब तक पोल करें जब तक status किसी अंतिम स्थिति तक न पहुँच जाए।

`status`	`outcome`	अर्थ
`pending`	`pending`	यूज़र ने अभी कैप्चर पूरा नहीं किया है — पोल करते रहें
`processing`	`pending`	कैप्चर हो गया, परिणाम की गणना हो रही है — पोल करते रहें
`completed`	`matched`	लॉगिन सफल — `authToken` मौजूद है
`completed`	`no_match`	बायोमेट्रिक किसी भी रिकॉर्ड से मेल नहीं खाया
`completed`	`inconclusive`	कैप्चर सफल रहा, लेकिन उसे हल नहीं किया जा सका
`expired`	—	लिंक एक्सपायर हो गया — स्टेप 1 से दोबारा शुरू करें
`canceled`	—	सेशन रद्द कर दिया गया — स्टेप 1 से दोबारा शुरू करें

सेशन को पोल करते समय intent-विशिष्ट अतिरिक्त एरर:

HTTP	स्थिति
`400`	SIGNUP — बायोमेट्रिक पहचान पहले से पंजीकृत है (डुप्लिकेट अकाउंट)
`400`	SIGNIN — बायोमेट्रिक पहचान पंजीकृत नहीं है (अकाउंट मौजूद नहीं है)

सफल रिस्पॉन्स:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

authToken सहेजें — इसके बाद के सभी Human Dashboard API अनुरोधों में इसे x-console-authorization हेडर के रूप में उपयोग करें।

अगर यूज़र के पास पहले से अकाउंट है और वह अपने पंजीकृत ईमेल पर भेजे गए एक बार उपयोग होने वाले कोड से प्रमाणीकरण करना पसंद करता है, तो बायोमेट्रिक के बजाय इस फ़्लो का उपयोग करें। ईमेल OTP के माध्यम से signup समर्थित नहीं है — पहली बार पंजीकरण के लिए बायोमेट्रिक फ़्लो का उपयोग करें।

स्टेप 1: OTP भेजें

curl -X POST https://api.humantoken.unico.app/api/console/v1/auth/email/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]"
  }'

नोट

ईमेल किसी मौजूदा अकाउंट का होना चाहिए। अगर कोई अकाउंट नहीं मिलता, तो स्टेप 2 (OTP सत्यापित करें) 404 Not Found लौटाता है।

रिस्पॉन्स:

{
  "session": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345"
  }
}

sessionId सहेजें। दिए गए ईमेल पते पर 6 अंकों का कोड भेजा जाता है।

स्टेप 2: OTP सत्यापित करें

curl https://api.humantoken.unico.app/api/console/v1/auth/email/sessions/{sessionId}/{code}

HTTP	स्थिति
`200`	कोड वैध है — `authToken` मौजूद है
`400`	कोड गलत है (`invalid otp code`)
`400`	OTP पहले ही उपयोग हो चुका है, अधिकतम प्रयास पूरे हो गए हैं, या एक्सपायर हो गया है
`404`	ईमेल पंजीकृत नहीं है

सफल रिस्पॉन्स:

{
  "result": {
    "sessionId": "b3f1a2c4-0000-0000-0000-abcdef012345",
    "status": "completed",
    "outcome": "matched",
    "authToken": "eyJhbGciOiJSUzI1NiJ9..."
  }
}

चरण 2 — अपना संगठन सेट अप करें

स्टेप 3: अपना संगठन बनाएं

नोट

यह कॉल केवल एक बार की जा सकती है। यह आपका tenant प्रोविज़न करती है और आपका branchId जनरेट करती है।

कोई भी देश स्वीकार्य है। ISO 3166-1 alpha-3 तीन-अक्षरीय कोड का उपयोग करें (जैसे BRA, USA, MEX, DEU, IND)। taxId सभी देशों के लिए वैकल्पिक है।

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "logo": "https://acme.com/logo.png",
    "allowedDomains": ["https://app.acme.com"]
  }'

रिस्पॉन्स:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

branchId सहेजें — यह आपकी डिफ़ॉल्ट ब्रांच की पहचान करता है और ब्रांच तथा एक्सेस कुंजियों के प्रबंधन में उपयोग होता है।

स्टेप 4: एक एक्सेस कुंजी बनाएं

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "production-key"
  }'

रिस्पॉन्स:

{
  "accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"
}

चेतावनी

accessKey केवल एक बार लौटाई जाती है और इसे दोबारा प्राप्त नहीं किया जा सकता। इसे तुरंत अपने सीक्रेट्स मैनेजर में HUMAN_TOKEN_ACCESS_KEY के रूप में संग्रहीत करें।

यह मान वही x-unico-accesskey हेडर है जो सभी Human Token API अनुरोधों में उपयोग होता है।

अब आपके पास क्या है

मान	इसका उपयोग कहाँ करें
`branchId`	अपनी डिफ़ॉल्ट ब्रांच की पहचान करना; ब्रांच-विशिष्ट एक्सेस कुंजियाँ बनाना
`accessKey`	सभी Human Token अनुरोधों में `x-unico-accesskey` हेडर

अपने संगठन का प्रबंधन

संगठन प्राप्त करें

curl https://api.humantoken.unico.app/api/console/v1/organization/<organizationId> \
  -H "x-console-authorization: <authToken>"

रिस्पॉन्स:

{
  "organization": {
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "tenantId": "tenant-acme-prod",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "taxId": "12345678000195"
  }
}

संगठन अपडेट करें

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "e5d3f1a2-0000-0000-0000-abcdef012345",
    "name": "Acme Corp",
    "responsibleEmail": "[email protected]",
    "websiteUrl": "https://acme.com",
    "countryCode": "BRA",
    "taxId": "12345678000195",
    "logo": "https://acme.com/logo-updated.png",
    "allowedDomains": ["https://app.acme.com", "https://checkout.acme.com"]
  }'

एक्सेस कुंजियों का प्रबंधन

कुंजियों की सूची देखें (केवल मेटाडेटा — सीक्रेट कभी नहीं लौटाया जाता):

curl https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>"

कुंजी रोटेट करें (पुरानी कुंजी तुरंत अमान्य हो जाती है):

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys/rotate \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

कुंजी रद्द करें (अपरिवर्तनीय):

curl -X DELETE https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{"accessKey": "uip_ak.prod.a1b2c3d4.e5f6g7h8.i9j0k1l2"}'

ब्रांच का प्रबंधन

ब्रांच आपको अपने संगठन के कॉन्फ़िगरेशन (नाम, लोगो, अनुमत डोमेन) को प्रोडक्ट या एनवायरनमेंट के अनुसार विभाजित करने देती हैं। प्रत्येक ब्रांच की अपनी एक्सेस कुंजियाँ होती हैं, इसलिए ब्रांच का संदर्भ अनुरोध में उपयोग की गई कुंजी से अपने-आप तय हो जाता है — CreateProcess में branchId भेजने की आवश्यकता नहीं है।

ब्रांच बनाएं

curl -X POST https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile App",
    "logo": "https://acme.com/mobile-logo.png",
    "allowedDomains": ["https://mobile.acme.com"]
  }'

रिस्पॉन्स:

{
  "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
}

branchId सहेजें — ब्रांच-विशिष्ट एक्सेस कुंजी बनाते समय इसका उपयोग करें।

ब्रांच अपडेट करें

curl -X PUT https://api.humantoken.unico.app/api/console/v1/organization/branches \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345",
    "name": "Mobile App v2",
    "logo": "https://acme.com/mobile-logo-v2.png",
    "allowedDomains": ["https://mobile.acme.com", "https://app.acme.com"]
  }'

ब्रांच-विशिष्ट एक्सेस कुंजी बनाएं

किसी विशेष ब्रांच तक सीमित एक्सेस कुंजी जनरेट करने के लिए, अनुरोध बॉडी में branchId शामिल करें:

curl -X POST https://api.humantoken.unico.app/api/console/v1/access-keys \
  -H "x-console-authorization: <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "mobile-app-key",
    "branchId": "7ab1c2d3-0000-0000-0000-abcdef012345"
  }'

रिस्पॉन्स:

{
  "accessKey": "uip_ak.prod.z9y8x7w6.v5u4t3s2.r1q0p9o8"
}

चेतावनी

accessKey केवल एक बार लौटाई जाती है। इसे तुरंत संग्रहीत करें। इस कुंजी से प्रमाणित कोई भी CreateProcess अनुरोध अपने-आप इससे जुड़े ब्रांच कॉन्फ़िगरेशन का उपयोग करेगा।

अपने क्रेडेंशियल सेट अप करने के दो तरीके​

Dashboard का उपयोग करना​

बेस URL​

प्रमाणीकरण के तरीके​

बायोमेट्रिक लॉगिन intent​

चरण 1 — प्रमाणीकरण करें​

स्टेप 1: बायोमेट्रिक लॉगिन सेशन शुरू करें​

स्टेप 2: सेशन के हल होने तक पोल करें​

चरण 1 (विकल्प) — ईमेल OTP signin​

स्टेप 1: OTP भेजें​

स्टेप 2: OTP सत्यापित करें​

चरण 2 — अपना संगठन सेट अप करें​

स्टेप 3: अपना संगठन बनाएं​

स्टेप 4: एक एक्सेस कुंजी बनाएं​

अब आपके पास क्या है​

अपने संगठन का प्रबंधन​

संगठन प्राप्त करें​

संगठन अपडेट करें​

एक्सेस कुंजियों का प्रबंधन​

ब्रांच का प्रबंधन​

ब्रांच बनाएं​

ब्रांच अपडेट करें​

ब्रांच-विशिष्ट एक्सेस कुंजी बनाएं​

अपने क्रेडेंशियल सेट अप करने के दो तरीके

Dashboard का उपयोग करना

बेस URL

प्रमाणीकरण के तरीके

बायोमेट्रिक लॉगिन intent

चरण 1 — प्रमाणीकरण करें

स्टेप 1: बायोमेट्रिक लॉगिन सेशन शुरू करें

स्टेप 2: सेशन के हल होने तक पोल करें

चरण 1 (विकल्प) — ईमेल OTP signin

स्टेप 1: OTP भेजें

स्टेप 2: OTP सत्यापित करें

चरण 2 — अपना संगठन सेट अप करें

स्टेप 3: अपना संगठन बनाएं

स्टेप 4: एक एक्सेस कुंजी बनाएं

अब आपके पास क्या है

अपने संगठन का प्रबंधन

संगठन प्राप्त करें

संगठन अपडेट करें

एक्सेस कुंजियों का प्रबंधन

ब्रांच का प्रबंधन

ब्रांच बनाएं

ब्रांच अपडेट करें

ब्रांच-विशिष्ट एक्सेस कुंजी बनाएं