प्रमाणीकरण

सभी IDCloud APIs (Web & SDK और API contracts) OAuth2 with JWT Bearer Grant Type (RFC 7523) का उपयोग करते हैं। आप अपने back-end पर एक short-lived JWT assertion उत्पन्न करते हैं, उसे Bearer token के लिए exchange करते हैं, और उस token का उपयोग हर बाद की call में करते हैं।

यह कभी भी client side पर न करें

JWT assertion केवल आपके back-end पर उत्पन्न किया जाना चाहिए। अपनी private key को front-end code, mobile apps, repositories, या logs में कभी भी उजागर न करें।

Credentials प्राप्त करना

Token उत्पन्न करने से पहले, आपको Unico द्वारा प्रावधानित एक service account की आवश्यकता है। Unico support से संपर्क करें और प्रदान करें:

• Service account नाम (अधिकतम 12 characters)
• जिम्मेदार व्यक्ति का नाम, ईमेल और फ़ोन (केवल Brazil, US या Mexico नंबर)

आपको प्राप्त होगा:

• अद्वितीय account नाम
• Tenant ID
• Base JWT payload
• Private key file (.pem format)

प्रति वातावरण एक account

UAT और Production के लिए अलग service accounts रखें।

JWT assertion बनाना

Assertion एक JWT है compact JWS format में: {Base64url(Header)}.{Base64url(Payload)}.{Base64url(Signature)}।

Header

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload

Claim	मान	नोट्स
iss	<account_name>@<tenant_id>.iam.acesso.io	आपके credentials के साथ प्रदान किया गया
aud	https://identityhomolog.acesso.io (UAT) या https://identity.acesso.io (Production)	token endpoint host से मेल खाना चाहिए
scope	*	सभी अनुमतियाँ प्रदान करता है
iat	Unix timestamp (seconds)	JWT जारी होने का समय
exp	iat + अधिकतम 3600	iat से 1 घंटे से अधिक नहीं हो सकता

{
  "iss": "[email protected]",
  "aud": "https://identity.acesso.io",
  "scope": "*",
  "iat": 1738086000,
  "exp": 1738089600
}

Signature

Unico द्वारा प्रदान की गई .pem private key के साथ RS256 (RSA + SHA-256) का उपयोग करके header + payload sign करें।

अतिरिक्त claims न जोड़ें

ऊपर सूचीबद्ध नहीं किया गया कोई भी फ़ील्ड (जैसे sub, jti, nbf) 1.2.22 त्रुटि का कारण बनेगा। केवल दिखाए गए claims का उपयोग करें।

Token का अनुरोध करना

Token endpoint दोनों contracts के लिए समान है:

वातावरण	Endpoint
Production	POST https://identity.acesso.io/oauth2/token
UAT	POST https://identityhomolog.acesso.io/oauth2/token

Request

पैरामीटर	मान
Content-Type	application/x-www-form-urlencoded
grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	आपका signed JWT

cURL

curl -X POST https://identity.acesso.io/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
  -d "assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Node.js

import jwt from 'jsonwebtoken';
import fs from 'fs';
import qs from 'querystring';

const privateKey = fs.readFileSync('./private-key.pem');
const now = Math.floor(Date.now() / 1000);

const assertion = jwt.sign(
  {
    iss: '[email protected]',
    aud: 'https://identity.acesso.io',
    scope: '*',
    iat: now,
    exp: now + 3600,
  },
  privateKey,
  { algorithm: 'RS256' }
);

const res = await fetch('https://identity.acesso.io/oauth2/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: qs.stringify({
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion,
  }),
});

const { access_token, expires_in } = await res.json();

Python

import time
import jwt  # PyJWT
import requests

with open("private-key.pem", "rb") as f:
    private_key = f.read()

now = int(time.time())

assertion = jwt.encode(
    {
        "iss": "[email protected]",
        "aud": "https://identity.acesso.io",
        "scope": "*",
        "iat": now,
        "exp": now + 3600,
    },
    private_key,
    algorithm="RS256",
)

response = requests.post(
    "https://identity.acesso.io/oauth2/token",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": assertion,
    },
)

token_data = response.json()
access_token = token_data["access_token"]

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

फ़ील्ड	प्रकार	विवरण
access_token	string	JWT access token। सभी API calls पर Authorization: Bearer <token> में उपयोग करें।
expires_in	integer	सेकंड में समाप्ति समय। उदाहरण: 3600।
token_type	string	हमेशा Bearer।

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

हर API request के Authorization header में token जोड़ें। Header दोनों contracts के लिए समान है — जो भिन्न होता है वह आपके द्वारा call किए जा रहे API का host और path है:

Contract	Production host	UAT host
Web & SDK	https://api.idcloud.unico.app	https://api.idcloud.uat.unico.app
API	https://api.id.unico.app	https://api.id.uat.unico.app

Web & SDK — Authorization एकमात्र आवश्यक auth header है:

curl -X POST https://api.idcloud.unico.app/client/v1/process \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

API — Authorization के साथ APIKEY header का उपयोग किया जाता है:

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Token नवीनीकरण

Tokens 3600 सेकंड के बाद समाप्त होते हैं। अपने back-end में सक्रिय नवीनीकरण implement करें:

• Token प्रतिक्रिया से expires_in track करें और समाप्ति timestamp संग्रहीत करें।
• समाप्ति से 10 मिनट या उससे कम बचे होने पर नया token अनुरोध करें।
• नवीनीकरण trigger करने के लिए production में 401 की प्रतीक्षा कभी न करें।

API reference

Token endpoint का पूर्ण OpenAPI विनिर्देश authentication.yaml में उपलब्ध है।

विधि	Path	विवरण
POST	/oauth2/token	Bearer access token के लिए signed JWT assertion exchange करें

त्रुटि कोड

कोड	विवरण	कार्रवाई
1.0.1	iss निर्माण में प्रदान की गई ID गलत है	सत्यापित करें कि iss फ़ील्ड private key उत्पन्न होने पर प्रदान किए गए tenant ID से मेल खाता है
1.0.14	Application सक्रिय नहीं है	project manager से जांचें कि उपयोग की जा रही application सक्रिय है या नहीं
1.1.1	scope पैरामीटर प्रदान नहीं किया गया	अपने JWT payload में "scope": "*" जोड़ें
1.2.4	JWT assertion अमान्य	JWT assertion अब मान्य नहीं है। दो कारण: (a) वर्तमान समय exp से आगे है (JWT सच में समाप्त हो गया — प्रत्येक token request के लिए नया assertion उत्पन्न करें); या (b) exp iat + 3600 से अधिक है (जीवनकाल बहुत लंबा — exp को iat + 3600 पर सीमित करें)।
1.2.5	JWT सत्यापन विफल	JWT को सत्यापित नहीं किया जा सकता। पैरामीटर सत्यापित करें और सुनिश्चित करें कि यह RS256 और सही private key से sign किया गया है
1.2.6	Private key अब मान्य नहीं है	JWT sign करने के लिए उपयोग की गई private key अब स्वीकार्य नहीं है। account के लिए नए credentials अनुरोध करें
1.2.7	JWT पहले ही उपयोग किया जा चुका है	JWT अब स्वीकार्य नहीं है क्योंकि इसका पहले ही उपयोग किया जा चुका है। प्रत्येक token request के लिए नया assertion उत्पन्न करें
1.2.11	Account सक्रिय नहीं है	उपयोग किया गया account सक्रिय नहीं है
1.2.14	Account में आवश्यक अनुमतियाँ नहीं हैं	उपयोग किए गए account में आवश्यक अनुमतियाँ नहीं हैं
1.2.18	Account अस्थायी रूप से लॉक है	अमान्य प्रमाणीकरण प्रयासों की संख्या से अधिक होने के कारण account अस्थायी रूप से लॉक किया गया है
1.2.19	अनधिकृत user impersonation	JWT में एक sub claim है जो ऐसे account की ओर इशारा करता है जो impersonation के लिए अधिकृत नहीं है। payload से sub claim हटाएं।
1.2.20	JWT decoding विफल	JWT decode करने में विफल। token format सत्यापित करें और सुनिश्चित करें कि यह RS256 से sign किया गया है।
1.2.21	गलत private key / Authentication विफल	JWT signature को इस account की किसी भी ज्ञात key के विरुद्ध सत्यापित नहीं किया जा सका। सत्यापित करें कि आप इस service account और environment के लिए सही .pem private key उपयोग कर रहे हैं।
1.2.22	Payload में अनुमत नहीं फ़ील्ड	JWT में अतिरिक्त payload फ़ील्ड हैं जो अनुमत नहीं हैं। इस guide में सूचीबद्ध नहीं किए गए किसी भी claim को हटाएं (जैसे sub, jti, nbf)। नोट: यदि आपने sub claim शामिल की और 1.2.19 प्राप्त हुआ, तो वह त्रुटि प्राथमिकता लेती है।
1.3.1	IP access प्रतिबंध	आपका IP इस account के लिए allowlist में नहीं है
1.3.2	समय-आधारित access प्रतिबंध	अनुरोध इस account के लिए अनुमत समय विंडो के बाहर है

आगे क्या

• Environments — sandbox बनाम production hosts
• Web & SDK — Create Process — प्रमाणीकरण के बाद पहला call
• API — Create Process — प्रमाणीकरण के बाद पहला call