ਪ੍ਰਮਾਣੀਕਰਨ
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 ਉਸ ਵੇਲੇ ਕੁੰਜੀ ਦੀ ਜਾਂਚ ਨਹੀਂ ਕਰ ਸਕਿਆ; ਕੁਝ ਨਹੀਂ ਕੀਤਾ ਗਿਆ, ਮੁੜ ਕੋਸ਼ਿਸ਼ ਕਰੋ |
ਕੁੰਜੀਆਂ ਸੁਰੱਖਿਅਤ ਰੱਖਣਾ
- ਹਰ ਐਪਲੀਕੇਸ਼ਨ ਅਤੇ ਇਨਵਾਇਰਨਮੈਂਟ ਲਈ ਵੱਖਰੀ ਕੁੰਜੀ ਰੱਖੋ, ਸਿਰਫ਼ ਲੋੜੀਂਦੇ ਦਾਇਰਿਆਂ ਨਾਲ। ਕੁੰਜੀ ਬਾਹਰ ਆਉਣ ਦਾ ਅਸਰ ਸੀਮਿਤ ਰਹਿੰਦਾ ਹੈ ਅਤੇ ਉਸ ਨੂੰ ਮਿਟਾਉਣ ਨਾਲ ਇੱਕੋ ਐਪਲੀਕੇਸ਼ਨ ਰੁਕਦੀ ਹੈ।
- ਕੁੰਜੀਆਂ ਆਪਣੇ ਸਰਵਰਾਂ ਉੱਤੇ ਰੱਖੋ, ਕੋਡ, ਲਾਗਾਂ ਜਾਂ ਬ੍ਰਾਊਜ਼ਰ ਤੇ ਐਪ ਵੱਲੋਂ ਡਾਊਨਲੋਡ ਕੀਤੀ ਕਿਸੇ ਚੀਜ਼ ਵਿੱਚ ਨਹੀਂ।
- ਕੁੰਜੀ ਬਦਲਣ ਲਈ ਨਵੀਂ ਬਣਾਓ, ਉਸ ਨੂੰ ਤੈਨਾਤ ਕਰੋ ਅਤੇ ਫਿਰ ਪੁਰਾਣੀ ਮਿਟਾਓ। ਮਿਟਾਈ ਕੁੰਜੀ ਤੁਰੰਤ ਕੰਮ ਕਰਨਾ ਬੰਦ ਕਰਦੀ ਹੈ।