Meduza Business API

کمپنیوں، اراکین، VPN تک رسائی اور راستوں کو اسی API سے منظم کریں جو کمپنی کا پینل استعمال کرتا ہے۔

پہلا ورژن: موجودہ معاہدے کے 169 طریقے — 191 مکمل ضروریات میں سے 169 نہیں۔ مسودہ دوسرے راستے اور طریقۂ کار استعمال کرتا ہے۔ پہلے ورژن کا مکمل میٹرکس: SSO/SCIM، ملکیت کی منتقلی، راؤٹرز پر فرم ویئر کی تنصیب، کنفیگریشن کی برآمد اور انوائسز کی قانونی تفصیلات خارج ہیں۔ notification-channels صرف پرانی فہرست ہے: اس کا معاہدہ اور email/webhook/in_app کی ترسیل پہلے ورژن سے خارج ہے۔ الرٹس کی سات اقسام نگرانی، آڈٹ اور API میں دستیاب ہیں؛ الگ دستخط شدہ webhooks API کے ذریعے ترسیل دائرے میں شامل رہتی ہے۔ راؤٹرز اور وسائل فی الحال صرف فہرست ہیں؛ billing-profile صرف میٹا ڈیٹا محفوظ کرتا ہے اور انوائسز سے منسلک نہیں۔

اجازت اور اختیارات

بنیادی راستہ: https://api.meduzavpn.com/api/business/v1۔ انٹرفیس موجودہ صارف سیشن استعمال کرتا ہے۔ خودکاری کے لیے کمپنی کے پینل میں API کلائنٹ بنائیں اور جاری ہوتے وقت سیکرٹ محفوظ کر لیں۔

curl -X POST https://api.meduzavpn.com/api/business/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_SECRET

curl https://api.meduzavpn.com/api/business/v1/organizations/ORGANIZATION_ID/members \
  -H "Authorization: Bearer TOKEN"

حاصل شدہ ٹوکن Authorization: Bearer TOKEN میں بھیجیں۔ ٹوکن ایک گھنٹے کے لیے اور صرف اسی کمپنی میں درست ہے جس نے کلائنٹ جاری کیا۔ کلائنٹ غیر فعال ہونے یا اسے بنانے والے ایڈمن کے اختیارات ختم ہونے پر رسائی منسوخ ہو جاتی ہے۔

ادائیگی اور VPN کا اجرا

1. صارف سیشن سے POST /organizations کے ذریعے کمپنی بنائیں۔
2. subscription/quotes سے تخمینہ حاصل کریں: VPN کی تعداد، مدت اور purchase، renewal یا upgrade آپریشن۔
3. quote_id اور payment_method: stripe_card کو subscription/checkout میں بھیجیں۔
4. جواب 202 کا مطلب ہے کہ انوائس تیار ہو رہی ہے۔ payment_url ظاہر ہونے تک invoices پڑھتے رہیں، پھر اسی لنک سے ادائیگی کریں۔
5. ادائیگی کے ریکارڈ سے تصدیق کے بعد سبسکرپشن فعال ہو جاتی ہے۔ VPN کو catalog/vpn-locations سے pricing_id اور لازمی Idempotency-Key کے ساتھ بنائیں۔

پیکج 5 VPN سے شروع ہوتا ہے۔ فی VPN بنیادی قیمت: $5.99 ماہانہ یا $54.99 سالانہ۔ پیکج رعایت: 5–9 VPN — 5%، 10–99 — 10%، 100 سے زیادہ — 20%۔ ادائیگی کے بعد براؤزر میں واپسی، ادائیگی کی تصدیق کے بغیر رسائی نہیں دیتی۔

تجدید تعداد اور مدت برقرار رکھتی ہے۔ پیکج بڑھانے پر بقیہ مدت کے لیے اضافی رقم کا حساب ہوتا ہے۔ سرور کو مستقل طور پر ہٹانے کے لیے POST /organizations/{organization_id}/vpns/{id}/retire کو confirm: true اور If-Match کے ساتھ استعمال کریں۔ ہٹانے کی تصدیق کے بعد جگہ خالی ہو جاتی ہے، سبسکرپشن کی قیمت نہیں بدلتی۔ کسی ملازم کو تفویض member_id کے طور پر بھیجی جاتی ہے؛ اس کے بغیر VPN رسائی کی تفویضات کے مطابق کمپنی کو دستیاب ہوتا ہے۔

کمپنی کا VPN کون استعمال کر سکتا ہے، یہ If-Match کے ساتھ PATCH /organizations/{organization_id}/vpns/{id} میں فیلڈ access طے کرتا ہے۔ company اسے کمپنی کے اُن تمام ارکان کے لیے کھول دیتا ہے جن کا کردار کنکشن کی اجازت دیتا ہے؛ member_ids اور group_ids کی فہرستیں خالی کر دی جاتی ہیں۔ restricted اسے صرف درج ملازمین اور درج گروپوں کے ارکان تک محدود کرتا ہے؛ خالی فہرستیں سب کی رسائی ختم کر دیتی ہیں۔ غیر خالی فہرستوں کے ساتھ company کو 422 کے ساتھ مسترد کیا جاتا ہے۔ GET کے جوابات اور /me/vpn-grants میں ہمیشہ data.access شامل ہوتا ہے، اُن VPN کے لیے بھی جو یہ فیلڈ آنے سے پہلے بنائے گئے تھے۔ access کے بغیر مگر member_ids یا group_ids والی درخواست پہلے کی طرح VPN کو restricted کر دیتی ہے۔ کسی ملازم کا مخصوص VPN ہمیشہ restricted ہوتا ہے۔ موڈ کی تبدیلی آڈٹ میں vpn_access_changed کے طور پر درج ہوتی ہے؛ رسائی محدود ہونے پر جن آلات کی رسائی ختم ہوئی اُن کی اسناد منسوخ کر دی جاتی ہیں۔

curl -X PATCH https://api.meduzavpn.com/api/business/v1/organizations/ORGANIZATION_ID/vpns/VPN_ID \
  -H "Authorization: Bearer TOKEN" \
  -H 'If-Match: "3"' \
  -H "Idempotency-Key: vpn-access-1" \
  -H "Content-Type: application/json" \
  -d '{"access":"company"}'

راستے اور ٹریفک سیٹس

سیٹ سائٹس یا نیٹ ورکس بیان کرتا ہے، اور قاعدہ عمل منتخب کرتا ہے: کوئی مخصوص VPN، براہِ راست یا پابندی۔ ممالک اور علاقے catalog/traffic-presets سے استعمال کریں۔ first-match موڈ میں قواعد اوپر سے نیچے جانچے جاتے ہیں، زیادہ سے زیادہ 128؛ «باقی ٹریفک» کے لیے پابندی دستیاب نہیں۔

محفوظ کرنے سے مسودہ بنتا ہے۔ جانچ چلائیں، پھر If-Match کے ساتھ شائع کریں۔ policy-deployments دیکھیں: قطار میں ہونا اور ڈیوائس کی تصدیق سے نافذ ہونا الگ حالتیں ہیں۔ VPN سے کنکشن کلائنٹ ایپ قائم کرتی ہے۔

کردار، گروپس اور ڈیوائسز

GET /organizations/{id}/roles بلٹ اِن اور اپنے بنائے ہوئے کردار، اختیارات کی تعریفیں اور can_manage نشان واپس کرتا ہے۔ مالک ایڈمن، ملازم یا مالیاتی کردار کی بنیاد پر اپنا کردار بناتا ہے اور صرف ضروری اختیارات رکھتا ہے۔ تفویض PATCH members/{id} سے ہوتی ہے: role اور custom_role_id۔ اختیارات کی تبدیلی اس صارف کے بنائے ہوئے API کلائنٹس پر بھی لاگو ہوتی ہے۔

کردار پینل میں کارروائیوں کی اجازت دیتا ہے۔ group_ids ملازم کو VPN اور روٹنگ پیکج تفویض کرتا ہے؛ گروپ کی رکنیت انتظامی اختیارات نہیں دیتی۔ مالک کا کردار اپنے کردار میں نقل نہیں کیا جا سکتا۔ ملازمین کو تفویض شدہ کردار حذف نہیں کیا جا سکتا۔

ڈیوائسز کو display_name، مالک اور VPN کی معلومات ملتی ہیں۔ PATCH devices/{id} صرف نام بدلتا ہے اور If-Match سے جانچتا ہے۔ POST devices/{id}/revocations منسوخی کی درخواست کرتا ہے؛ حتمی حالت کی تصدیق نوڈ کرتا ہے۔ اپنی ڈیوائسز /me/devices سے دستیاب ہیں۔ last_api_ip فیلڈ API کی ترسیل کا پتہ ہے، VPN کنکشن کا نہیں۔ ایپ کی بتائی گئی نام اور ماڈل اجازت کے لیے استعمال نہیں ہوتے۔

کنکشنز اور منزلوں کا لاگ

GET /organizations/{id}/employee-analytics مشاہدہ شدہ کنکشنز، حالت کی تبدیلیاں اور 7 دن کی گھنٹہ وار تاریخ دکھاتا ہے۔ غائب پیمائش کو صفر سے نہیں بدلا جاتا؛ سیشنز کی تعداد ملازم کے کام کا وقت نہیں۔

GET /organizations/{id}/activity نوڈ کی درج کردہ کنکشن درخواستیں واپس کرتا ہے: مطلوبہ ڈومین یا IP، پورٹ، پروٹوکول، وقت، فیصلہ، ڈیوائس اور ملازم۔ فلٹرز: from، to، member_id، action، search؛ صفحات: cursor اور limit۔ ڈومین کلائنٹ کنکشن کی درخواست میں بھیجتا ہے، یہ HTTPS ڈیکرپٹ کر کے حاصل نہیں کیا جاتا۔

ڈیٹا جمع کرنا بطورِ طے شدہ بند ہے۔ مالک activity-settings کو PATCH کے ذریعے {"enabled": true} اور If-Match کے ساتھ بدلتا ہے۔ پڑھنے کے لیے activity.read درکار ہے۔ جمع کرنا فعال ہونے پر ایپ ملازم کو اطلاع دکھاتی ہے؛ کلید کے اجرا کے لیے کلید کے مالک کی تصدیق کے بعد X-Corporate-Activity-Version کی تازہ توثیق ضروری ہے۔ پرانا کلائنٹ اس موڈ کے لیے کلید حاصل نہیں کرتا۔

ذخیرہ فی کمپنی 7 دن اور 100,000 واقعات تک محدود ہے؛ نوڈ کا بفر 24 گھنٹے تک رکھتا ہے۔ coverage تازگی، ناقابلِ رسائی ڈیوائسز اور بفر کے نقصانات بتاتا ہے۔ ذاتی VPN، ڈیوائس کا براہِ راست ٹریفک، نوڈ تک پہنچنے سے پہلے مقامی پابندیاں، HTTPS راستے، درخواستوں کا مواد اور کارکردگی کی درجہ بندی درج نہیں ہوتے۔ جمع کرنا بند کرنے سے چھوٹی ہوئی تاریخ بحال نہیں ہوتی اور پہلے جمع شدہ ریکارڈ فوراً حذف نہیں ہوتے: ذخیرے کی مدت لاگو رہتی ہے۔

زمرے اور نیٹ ورک سرگرمی کا وقت

لاگ کے جواب میں analysis شامل ہے: زمروں، ملازمین اور گھنٹوں کے لحاظ سے تقسیم، اہم منزلیں اور active_minutes کی تعداد۔ خلاصے منتخب مدت کے تمام محفوظ واقعات پر شمار ہوتے ہیں، خام لاگ کے صفحے سے قطع نظر۔ category فلٹر سے مخصوص واقعات تک جائیں۔

ایک فعال منٹ کسی ملازم کا وہ منفرد منٹ ہے جس میں نوڈ نے درخواست دیکھی۔ یہ کسی سائٹ کو دیکھنے یا کام کا دورانیہ نہیں: پس منظر کا ٹریفک بھی شمار ہوتا ہے، اور ایک منٹ میں زمرے ایک دوسرے پر آ سکتے ہیں۔ کل وقت الگ سے شمار ہوتا ہے اور زمروں کا مجموعہ نہیں۔

مالک لاگ کی ترتیبات میں زیادہ سے زیادہ 64 classification_rules قواعد مقرر کرتا ہے: ڈومین اور زمرہ۔ یہ ذیلی ڈومینز پر بھی لاگو ہوتے ہیں اور بلٹ اِن فہرست پر ترجیح رکھتے ہیں۔ نامعلوم منزلیں الگ زمرے میں رہتی ہیں۔ موجودہ قواعد پوری منتخب مدت کی درجہ بندی کرتے ہیں؛ جواب درجہ بندی کا ورژن بتاتا ہے۔

کارپوریٹ کنکشنز کی منزلوں پر کارروائی ہوتی ہے، HTTPS مواد، مکمل URL یا ذاتی ٹریفک پر نہیں۔ اطلاع کی توثیق کمپنی میں ہر ملازم کے لیے ایک بار محفوظ ہوتی ہے؛ زمروں، گروپس یا جمع کرنے کے موڈ کی تبدیلی پر اسی اطلاع کی دوبارہ توثیق ضروری نہیں۔ نامکمل کوریج کے نشانات اور truncated کو سرگرمی کی عدم موجودگی نہ سمجھا جائے۔

واقعات کی سبسکرپشن

پورٹ 443 پر عوامی HTTPS URL اور audit.event، * یا groups.created، members.updated اور وسائل کی دیگر تبدیلیوں کے واقعات کے ساتھ webhooks بنائیں۔ سیکرٹ صرف بناتے یا بدلتے وقت دکھایا جاتا ہے۔

Meduza-Signature: t=UNIX_SECONDS,v1=HEX_SIGNATURE
Meduza-Event-Id: EVENT_ID
Meduza-Delivery-Id: DELIVERY_ID

HEX_SIGNATURE = HMAC-SHA256(secret, timestamp + "." + RAW_JSON_BODY)

دستخط کی جانچ متن کے اصل بائٹس پر کریں، timestamp کی اجازت شدہ عمر اور event ID کی تکرار بھی دیکھیں۔ سیکرٹ بدلتے وقت قطار میں موجود واقعات کے لیے پچھلا سیکرٹ رکھیں۔ کوئی بھی 2xx کامیابی ہے؛ باقی جوابات بڑھتے وقفوں سے آٹھ کوششوں تک دہرائے جاتے ہیں۔ تاریخ اور دستی دوبارہ ترسیل deliveries سے دستیاب ہیں۔ کامیاب اور منسوخ ترسیلات 30 دن تک، فی webhook زیادہ سے زیادہ 2,000 محفوظ رہتی ہیں۔ قطار اور ناکامیاں 1,000 واقعات تک محدود ہیں؛ بھر جانے پر سب سے پرانے واقعات ہٹا دیے جاتے ہیں اور dropped_deliveries کاؤنٹر نقصان بتاتا ہے۔ اس صورت میں API کے ذریعے حالت ہم آہنگ کریں۔

ترسیل کم از کم ایک بار ہوتی ہے۔ API سے ہونے والی تبدیلیوں کے علاوہ انوائسز (invoices.updated)، سبسکرپشنز (subscriptions.updated)، VPN کی تیاری (vpns.updated) کی تصدیق شدہ تبدیلیاں اور الرٹس (alerts.created) بھی بھیجے جاتے ہیں۔ حالت بدلے بغیر دوبارہ پوچھنے سے نیا واقعہ نہیں بنتا۔ یہ نیٹ ورک ٹریفک کا بہاؤ نہیں۔ نجی IP، ری ڈائریکٹس اور اندرونی خدمات تک رسائی ممنوع ہے۔

API کے طریقے

معاہدہ لوڈ ہو رہا ہے…

فہرستوں کے صفحات اور فلٹرز

انوینٹری فہرستوں کے لیے limit=1..200 بھیجیں، پھر باقی پیرامیٹرز برقرار رکھتے ہوئے next_cursor سے cursor بھیجیں۔ limit/cursor کے بغیر پرانے کلائنٹس کو مکمل فہرست ملتی ہے: ڈیٹا کبھی خاموشی سے نہیں کاٹا جاتا۔ دستیاب ہیں status، member_id، user_id، vpn_id، search اور created_from/created_to (‏RFC3339، نچلی حد شامل، اوپری حد خارج)۔ رسائی فلٹرنگ سے پہلے اور ہر صفحے پر جانچی جاتی ہے۔ نامعلوم یا دہرائے گئے پیرامیٹرز 422 دیتے ہیں۔ سرگرمی لاگ کی فہرستیں الگ معاہدہ استعمال کرتی ہیں۔ ہر طریقے کے پیرامیٹرز۔

یہ ورژن کیا شامل کرتا ہے

انتظامی آڈٹ 90 دن تک، فی کمپنی زیادہ سے زیادہ آخری 10,000 واقعات محفوظ رہتا ہے؛ میعاد ختم شدہ idempotency ریکارڈ صاف کیے جاتے ہیں۔ یہ صفائی انوائسز اور سبسکرپشنز حذف نہیں کرتی۔ انوینٹری فہرستیں items، total اور next_cursor واپس کرتی ہیں؛ اگلا حصہ واضح limit/cursor پر ظاہر ہوتا ہے۔ ان کے بغیر مکمل جواب پرانے کلائنٹس کے ساتھ ہم آہنگ رہتا ہے۔ activity لاگ الگ سے کرسر اور دستاویزی فلٹرز کو سپورٹ کرتا ہے۔ idempotency کیش کے جوابات میں سیکرٹس دہرائے نہیں جاتے۔ کلید کی منسوخی کی تصدیق VPN سرور سے آتی ہے؛ رکنیت غیر فعال کرنے سے نیا اجرا فوراً رک جاتا ہے۔

نگرانی حقیقی کنکشنز اور بوجھ دکھاتی ہے۔ منزلوں کی تاریخ ایک الگ لاگ سے دستیاب ہے جسے واضح طور پر فعال کرنا ہوتا ہے۔ HTTPS مواد اور ملازمین کی کارکردگی کی درجہ بندی اس ڈیٹا میں شامل نہیں۔ SSO/SCIM اور توسیعی مسودے کے دیگر طریقے اس نافذ شدہ معاہدے کا حصہ نہیں۔

انتظامی غلطیاں application/problem+json واپس کرتی ہیں جس میں status، detail اور request_id ہوتے ہیں۔ OAuth ٹوکن کے اجرا کی غلطیاں error فیلڈ استعمال کرتی ہیں۔