ప్రామాణీకరణ
Oblic API ప్రతి కాల్లో Oblic సెట్టింగ్లలో పాత్ర, అవసరమైన అనుమతి పరిధులతో సృష్టించిన API కీని పంపాలి. కీని మీ సంస్థ అనుమతించిన IP చిరునామాలకు పరిమితం చేయవచ్చు. API v2 బదులుగా OAuth ప్రవేశ టోకెన్లను స్వీకరిస్తుంది.
కీని సృష్టించడం
Oblic లో సెట్టింగ్లు → API అనుసంధానం కింద కీలు సృష్టించండి. ప్రతి కీకి పేరు, పాత్ర (Owner, Admin లేదా User), దాని అప్లికేషన్కు అవసరమైన అనుమతి పరిధులు ఇవ్వండి. సృష్టించినప్పుడు మాత్రమే కీ ఒకసారి కనిపిస్తుంది; రహస్యాల నిర్వాహకంలో లేదా రక్షిత పర్యావరణ వేరియబుల్లో ఉంచండి. పోయిన కీని మళ్లీ చూపలేరు; మరొకటి సృష్టించిన తర్వాత పోయినదాన్ని తొలగించండి.
కీని పంపడం
Authorization హెడర్లో Bearer, ఒక ఖాళీ, తర్వాత కీని పంపండి:
కీతో కాల్
curl https://api.oblic.app/external/v1/key \
-H 'Authorization: Bearer YOUR_API_KEY'
API సర్వర్ల కోసం: బ్రౌజర్ క్రాస్-ఆరిజిన్ అభ్యర్థనకు సమాధానం ఇవ్వదు. కాబట్టి ఎవరైనా చదవగల వెబ్ పేజీ లేదా యాప్లో కీని ఉంచాల్సిన అవసరం లేదు.
అనుమతి పరిధులు
సృష్టించినప్పుడు ఇచ్చిన పరిధులను కీ కలిగి ఉంటుంది. ప్రతి రూట్ స్వీకరించే పరిధులను సూచిస్తుంది; వాటిలో ఏదైనా ఒకటి ఉన్న కీ దాన్ని కాల్ చేయవచ్చు. పరిధుల వ్యవస్థకు ముందు సృష్టించిన కీలో పరిచయాల ఈవెంట్లను నమోదు చేసే events:write మినహా అన్ని పరిధులు ఉంటాయి. ఈవెంట్లు పంపడానికి ఈ పరిధి ఉన్న కీ సృష్టించండి.
| పరిధి | కీ చేయగలిగేవి |
|---|---|
email:send | ఇమెయిల్ పంపడం; ఉపయోగించే ఇమెయిల్ టెంప్లేట్లు, పంపేవారి గుర్తింపులు చదవడం |
sms:send | SMS పంపడం; SMS ఖాతా, హెడర్లు, టెంప్లేట్లు చదవడం |
whatsapp:send | WhatsApp సందేశాలు పంపడం; WhatsApp నంబర్, టెంప్లేట్లు, గ్రహీతలు చదవడం |
messages:read | సందేశాల జాబితా, ప్రతి దాని ఫలితం, నివేదిక సారాంశం చదవడం |
templates:manage | ఇమెయిల్ టెంప్లేట్లు, SMS హెడర్లు మరియు టెంప్లేట్లు, WhatsApp నంబర్ మరియు టెంప్లేట్లు నిర్వహించడం |
identities:manage | పంపేవారి గుర్తింపులు నిర్వహించడం |
contacts:manage | పరిచయ జాబితాలు సృష్టించడం, వాటి జాబితా పొందడం, పరిచయాలు జోడించడం |
events:write | ఆర్డర్ల వంటి పరిచయాల ఈవెంట్లను నమోదు చేయడం (ఈవెంట్లు చూడండి) |
webhooks:manage | వెబ్హుక్లు, వాటి విఫల డెలివరీలు నిర్వహించడం |
accounts:manage | ఉపఖాతాలు నిర్వహించడం |
mcp:read, mcp:write Oblic MCP సర్వర్ కోసం, ఈ API కోసం కాదు. ప్రతి రూట్ పరిధులు ఎండ్పాయింట్లలో, OpenAPI పత్రంలోని x-oblic-scopes లో ఉంటాయి.
పాత్రలు
పరిధులు ఏవైనా, కీ పాత్ర దానికి అందుబాటులో ఉన్న రూట్లను నిర్ణయిస్తుంది:
- Owner, Admin కీలు అన్ని రూట్లను కాల్ చేయవచ్చు.
- User కీలు టెంప్లేట్లు, SMS హెడర్లు లేదా WhatsApp నంబర్ మార్చే, వెబ్హుక్లు లేదా ఉపఖాతాలు నిర్వహించే,
/external/v1/healthతనిఖీ చేసే రూట్లు మినహా అన్నింటిని కాల్ చేయవచ్చు. User కీనిtemplates:manage,webhooks:manageలేదాaccounts:manageతో సృష్టించలేరు. పాత కీ లేదా ఉపఖాతా కీ వంటి అన్ని పరిధులు ఉన్న కీ ఆ పరిధులను చూపినా, వాటిని వాడటానికి అనుమతి ఉండదు.
ఈ రూట్లలో అవసరమైన పరిధులేవీ లేని User కీకి 403 INSUFFICIENT_SCOPE వస్తుంది. 403 ROLE_NOT_ALLOWED అనేది పరిధి అవసరం లేని /external/v1/health వద్ద, కీకి అన్ని పరిధులు ఉన్నప్పుడు వస్తుంది.
అనుమతించిన IP చిరునామాలు
సెట్టింగ్లు → API అనుసంధానం → అనుమతించిన IP లు కింద సర్వర్లు కాల్ చేసే చిరునామాలు ఇవ్వండి: విడి IPv4 లేదా IPv6 చిరునామాలు లేదా 203.0.113.0/24 వంటి శ్రేణులు. జాబితా ఖాళీగా ఉంటే ఏ చిరునామా నుంచైనా కీ పనిచేస్తుంది; ఒక నమోదు చేరాక జాబితాలోని చిరునామాల నుంచి మాత్రమే పనిచేస్తుంది. మార్పు ఒక నిమిషంలో అమలవుతుంది.
మరో చిరునామా అభ్యర్థనకు 403 IP_NOT_ALLOWED వస్తుంది. Oblic చూసిన చిరునామాను సందేశం చూపుతుంది; దాన్నే జోడించాలి. ఉపఖాతా అభ్యర్థనకూ సంస్థ జాబితా వర్తిస్తుంది.
కీని తనిఖీ చేయడం
ఏ కీ అయినా తన పేరు, పాత్ర, పరిధులు, ప్రస్తుతం చేయగల పనులను చదవవచ్చు.
సమాధానంలోని కొంత భాగం
{
"status": "success",
"data": {
"name": "Order service",
"role": "USER",
"scopes": ["email:send", "messages:read"],
"allScopes": false,
"organizationId": "ORG000R7ZM4Q2VXH00",
"capabilities": {
"scopes": [
{ "scope": "email:send", "action": "send email", "ownerOnly": false, "granted": true, "ready": true }
],
"verifiedSenders": [{ "identity": "example.com", "type": "Domain", "status": "verified" }],
"unverifiedSenders": [],
"defaultSender": "hello@example.com",
"allowedIps": ["203.0.113.0/24"],
"subAccount": false
}
},
"errors": null
}
capabilities ప్రతి పరిధిని కీ ఉపయోగించవచ్చా (granted), సంస్థ సిద్ధంగా ఉందా (ready) అని చెబుతుంది. ఉదాహరణకు ఇమెయిల్ పంపడానికి ధృవీకరించిన పంపేవారు అవసరం. సిద్ధంగా లేకపోతే కారణం reason లో ఉంటుంది.
తిరస్కరణలు
| స్థితి | cd | ఎప్పుడు |
|---|---|---|
| 401 | MISSING_API_KEY | Authorization: Bearer హెడర్ లేదు |
| 401 | INVALID_API_KEY | Oblic గుర్తించని కీ: తప్పుగా రాసినది లేదా తొలగించినది |
| 403 | IP_NOT_ALLOWED | కీ చెల్లుతుంది, కానీ IP చిరునామా అనుమతించిన జాబితాలో లేదు |
| 403 | INSUFFICIENT_SCOPE | రూట్ పరిధులేవీ కీకి లేవు; సందేశం, WWW-Authenticate హెడర్ అవసరమైనవి చూపుతాయి |
| 403 | ROLE_NOT_ALLOWED | /external/v1/health వద్ద User కీ లేదా Owner లేదా Admin కోసం ఉన్న రూట్లో అన్ని పరిధులు ఉన్న User కీ |
| 404 | ACCOUNT_NOT_FOUND | X-Oblic-On-Behalf-Of క్రియాశీల ఉపఖాతాను సూచించదు |
| 503 | AUTHENTICATION_UNAVAILABLE | అప్పుడు కీని తనిఖీ చేయడం Oblic కు సాధ్యం కాలేదు; ఏమీ చేయలేదు, మళ్లీ ప్రయత్నించండి |
కీలను సురక్షితంగా ఉంచడం
- ప్రతి అప్లికేషన్, పర్యావరణానికి వేరు కీ అవసరమైన పరిధులతో మాత్రమే వాడండి. కీ బయటపడితే ప్రభావం పరిమితం అవుతుంది; తొలగిస్తే ఒక అప్లికేషన్ మాత్రమే ఆగుతుంది.
- కీలను సర్వర్లలో ఉంచండి, కోడ్, లాగ్లు లేదా బ్రౌజర్, యాప్ డౌన్లోడ్ చేసే దేనిలోనూ కాదు.
- కీని మార్చడానికి కొత్తది సృష్టించి అమర్చాక పాతదాన్ని తొలగించండి. తొలగించిన కీ వెంటనే పనిచేయడం ఆపుతుంది.