Meduza Business API

Şirketleri, üyeleri, VPN erişimini ve rotaları şirket panelinin kullandığı API ile yönetin.

İlk sürüm: mevcut sözleşmenin 169 yöntemi — 191 hazır gereksinimin 169’u değil. Taslak farklı yollar ve süreçler kullanır. İlk sürümün tam matrisi: SSO/SCIM, sahipliğin devri, yönlendiricilere yazılım dağıtımı, yapılandırma dışa aktarımı ve faturalar için yasal bilgiler kapsam dışıdır. notification-channels yalnızca eski bir envanterdir: sözleşmesi ve email/webhook/in_app teslimatı ilk sürümün dışındadır. Yedi uyarı türü izleme, denetim ve API’de kullanılabilir; ayrı imzalı webhooks API’si üzerinden teslimat kapsamda kalır. Yönlendiriciler ve kaynaklar şimdilik yalnızca envanterdir; billing-profile faturalarla bağlantısı olmayan bir meta veri deposudur.

Yetkilendirme ve izinler

Temel yol: https://meduzacore.com/__api/api/business/v1. Arayüz mevcut kullanıcı oturumunu kullanır. Otomasyon için şirket panelinde bir API istemcisi oluşturun ve gizli anahtarı verildiği anda kaydedin.

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

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

Aldığınız belirteci Authorization: Bearer TOKEN içinde gönderin. Belirteç bir saat ve yalnızca istemciyi veren şirket içinde geçerlidir. İstemci devre dışı bırakıldığında veya onu oluşturan yöneticinin yetkileri kaldırıldığında erişim iptal edilir.

Ödeme ve VPN verme

1. Kullanıcı oturumundan POST /organizations ile şirketi oluşturun.
2. subscription/quotes ile fiyat teklifi alın: VPN sayısı, dönem ve purchase, renewal veya upgrade işlemi.
3. quote_id ve payment_method: stripe_card değerlerini subscription/checkout adresine gönderin.
4. 202 yanıtı faturanın hazırlandığı anlamına gelir. payment_url görünene kadar invoices okuyun ve bu bağlantıdan ödeyin.
5. Ödeme kaydı ödemeyi onayladıktan sonra abonelik etkinleşir. VPN’leri catalog/vpn-locations içindeki bir pricing_id ve zorunlu Idempotency-Key ile oluşturun.

Paket 5 VPN’den başlar. VPN başına taban fiyat: ayda $5.99 veya yılda $54.99. Paket indirimi: 5–9 VPN — %5, 10–99 — %10, 100 ve üzeri — %20. Ödemeden sonra tarayıcıya dönmek, ödeme doğrulanmadan erişim vermez.

Yenileme adedi ve dönemi korur. Paketi büyütmek kalan süre için fark ücreti hesaplar. Bir sunucuyu kalıcı olarak kaldırmak için POST /organizations/{organization_id}/vpns/{id}/retire yöntemini confirm: true ve If-Match ile kullanın. Yer, kaldırma onaylandıktan sonra boşalır; abonelik fiyatı değişmez. Bir çalışana atama member_id olarak gönderilir; bu olmadan VPN, erişim atamalarına göre şirketin kullanımındadır.

Şirket VPN’ini kimin kullanabileceğini If-Match ile gönderilen PATCH /organizations/{organization_id}/vpns/{id} isteğindeki access alanı belirler. company, rolü bağlantıya izin veren tüm şirket üyelerine açar; member_ids ve group_ids listeleri temizlenir. restricted, yalnızca listelenen çalışanlara ve listelenen grupların üyelerine sınırlar; boş listeler herkesin erişimini kaldırır. Boş olmayan listelerle birlikte company 422 ile reddedilir. GET yanıtları ve /me/vpn-grants, alan eklenmeden önce oluşturulan VPN’ler dahil, her zaman data.access içerir. access olmadan ancak member_ids veya group_ids ile gönderilen istek, önceden olduğu gibi VPN’i restricted yapar. Çalışana ayrılmış VPN her zaman restricted olur. Mod değişiklikleri denetim kaydına vpn_access_changed olarak yazılır; erişim daraltıldığında erişimini kaybeden cihazların anahtarları iptal edilir.

curl -X PATCH https://meduzacore.com/__api/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"}'

Rotalar ve trafik setleri

Bir set siteleri veya ağları tanımlar, bir kural eylemi seçer: belirli bir VPN, doğrudan veya engelleme. Ülke ve bölgeleri catalog/traffic-presets içinden kullanın. first-match modunda kurallar yukarıdan aşağıya denetlenir, en fazla 128; “Diğer trafik” için engelleme kullanılamaz.

Kaydetmek bir taslak oluşturur. Doğrulamayı çalıştırın, ardından If-Match ile yayınlayın. policy-deployments durumunu kontrol edin: kuyruğa alınmak ile cihaz tarafından uygulandığının onaylanması farklı durumlardır. VPN’e bağlantıyı istemci uygulaması kurar.

Roller, gruplar ve cihazlar

GET /organizations/{id}/roles yerleşik ve özel rolleri, izin tanımlarını ve can_manage işaretini döndürür. Şirket sahibi; yönetici, çalışan veya finans rolünü temel alarak yalnızca gerekli izinleri bırakan özel bir rol oluşturur. Atama PATCH members/{id} ile yapılır: role ve custom_role_id. İzin değişiklikleri, o kullanıcının oluşturduğu API istemcilerini de etkiler.

Rol, paneldeki eylemlere izin verir. group_ids çalışana VPN’leri ve bir yönlendirme paketini atar; grup üyeliği yönetici yetkisi vermez. Sahip rolü özel bir role kopyalanamaz. Çalışanlara atanmış bir rol silinemez.

Cihazlar bir display_name, bir sahip ve VPN bilgisi alır. PATCH devices/{id} yalnızca adı değiştirir ve If-Match ile denetlenir. POST devices/{id}/revocations iptal ister; nihai durumu düğüm onaylar. Kendi cihazlarınıza /me/devices üzerinden erişilir. last_api_ip alanı API taşıma adresidir, VPN bağlantısının adresi değildir. Uygulamanın bildirdiği ad ve model yetkilendirmede kullanılmaz.

Bağlantılar ve hedef günlüğü

GET /organizations/{id}/employee-analytics gözlemlenen bağlantıları, durum değişikliklerini ve 7 günlük saatlik geçmişi gösterir. Eksik bir ölçüm sıfırla değiştirilmez; oturum sayısı çalışanın çalışma süresi değildir.

GET /organizations/{id}/activity düğümün kaydettiği bağlantı isteklerini döndürür: istenen alan adı veya IP, port, protokol, zaman, karar, cihaz ve çalışan. Filtreler: from, to, member_id, action, search; sayfalar: cursor ve limit. Alan adını istemci bağlantı isteğinde iletir; HTTPS şifresi çözülerek elde edilmez.

Toplama varsayılan olarak kapalıdır. Sahip, activity-settings ayarını PATCH ile {"enabled": true} ve If-Match göndererek değiştirir. Okuma için activity.read gerekir. Toplama açıkken uygulama çalışana bir bildirim gösterir; anahtar verilmesi, anahtar sahibinin doğrulanmasından sonra güncel bir X-Corporate-Activity-Version onayı gerektirir. Eski bir istemci bu mod için anahtar alamaz.

Saklama, şirket başına 7 gün ve 100.000 olayla sınırlıdır; düğüm arabelleği 24 saate kadar tutar. coverage güncelliği, erişilemeyen cihazları ve arabellek kayıplarını bildirir. Kişisel VPN’ler, cihazın doğrudan trafiği, düğüme ulaşmadan önceki yerel engellemeler, HTTPS yolları, istek içerikleri ve verimlilik puanlaması kaydedilmez. Toplamayı kapatmak eksik geçmişi geri getirmez ve daha önce toplanan kayıtları hemen silmez: saklama süresi geçerlidir.

Kategoriler ve ağ etkinliği süresi

Günlük yanıtı analysis içerir: kategorilere, çalışanlara ve saatlere göre dağılım, başlıca hedefler ve active_minutes sayısı. Özetler, ham günlüğün sayfasından bağımsız olarak seçilen dönemin tüm saklanan olayları üzerinden hesaplanır. category filtresi belirli olaylara geçmenizi sağlar.

Bir etkin dakika, düğümün bir istek gözlemlediği, çalışana ait benzersiz bir dakikadır. Bu, bir siteyi görüntüleme veya çalışma süresi değildir: arka plan trafiği de sayılır ve kategoriler aynı dakikada çakışabilir. Toplam süre ayrıca hesaplanır ve kategorilerin toplamı değildir.

Sahip, günlük ayarlarında en fazla 64 classification_rules kuralı belirler: alan adı ve kategori. Kurallar alt alan adlarına da uygulanır ve yerleşik dizinden önceliklidir. Bilinmeyen hedefler ayrı bir kategoride kalır. Geçerli kurallar seçilen dönemin tamamını sınıflandırır; yanıt sınıflandırma sürümünü belirtir.

İşlenen şey kurumsal bağlantıların hedefleridir; HTTPS içeriği, tam URL’ler veya kişisel trafik değildir. Bildirimin onayı şirketteki her çalışan için bir kez saklanır; kategorileri, grupları veya toplama modunu değiştirmek aynı bildirimin yeniden onaylanmasını gerektirmez. Eksik kapsam işaretleri ve truncated etkinlik olmadığı şeklinde yorumlanmamalıdır.

Olay abonelikleri

443 numaralı portta herkese açık bir HTTPS URL’si ve audit.event, * ya da groups.created, members.updated ve diğer kaynak değişikliği olaylarıyla webhooks oluşturun. Gizli anahtar yalnızca oluşturma veya yenileme sırasında gösterilir.

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)

İmzayı gövdenin ham baytlarına göre, timestamp’in izin verilen yaşını ve event ID tekrarını doğrulayın. Yenileme sırasında, kuyruğa alınmış olaylar için önceki gizli anahtarı saklayın. Her 2xx yanıtı başarıdır; diğer yanıtlar artan aralıklarla, en fazla sekiz deneme olarak yinelenir. Geçmiş ve elle yeniden gönderim deliveries üzerinden kullanılabilir. Başarılı ve iptal edilen teslimatlar 30 güne kadar, webhook başına en fazla 2.000 adet saklanır. Kuyruk ve hatalar 1.000 olayla sınırlıdır; taşma olursa en eski olaylar silinir ve dropped_deliveries sayacı kaybı bildirir. Bu durumda durumu API üzerinden eşitleyin.

Teslimat en az bir kez yapılır. API ile yapılan değişikliklerin yanı sıra faturalardaki (invoices.updated), aboneliklerdeki (subscriptions.updated), VPN hazır olma durumundaki (vpns.updated) onaylanmış değişiklikler ve uyarılar (alerts.created) da gönderilir. Durum değişmeden yapılan yeni sorgu yeni bir olay oluşturmaz. Bu bir ağ trafiği akışı değildir. Özel IP’ler, yönlendirmeler ve iç hizmetlere çağrılar yasaktır.

API yöntemleri

Sözleşme yükleniyor…

Liste sayfaları ve filtreleri

Envanter listeleri için limit=1..200, ardından diğer parametreleri koruyarak next_cursor içindeki cursor değerini gönderin. limit/cursor olmadan eski istemciler tam listeyi alır: veriler hiçbir zaman sessizce kesilmez. Kullanılabilenler: status, member_id, user_id, vpn_id, search ve created_from/created_to (RFC3339, alt sınır dahil, üst sınır hariç). Erişim filtrelemeden önce ve her sayfada denetlenir. Bilinmeyen veya tekrarlanan parametreler 422 döndürür. Etkinlik günlüğü listeleri ayrı bir sözleşme kullanır. Her yöntemin parametreleri.

Bu sürüm neleri kapsar

Yönetim denetim kaydı 90 güne kadar, şirket başına en fazla son 10.000 olay olarak saklanır; süresi dolan idempotency kayıtları temizlenir. Bu temizlik faturaları ve abonelikleri silmez. Envanter listeleri items, total ve next_cursor döndürür; devam, açık limit/cursor ile görünür. Bunlar olmadan tam yanıt eski istemcilerle uyumlu kalır. activity günlüğü ayrıca bir imleci ve belgelenen filtreleri destekler. Gizli anahtarlar idempotency önbelleğinden gelen yanıtlarda tekrarlanmaz. Onaylanmış anahtar iptali VPN sunucusundan gelir; üyeliğin devre dışı bırakılması yeni anahtar verilmesini hemen engeller.

İzleme gerçek bağlantıları ve yükü gösterir. Hedef geçmişi, açıkça etkinleştirilmesi gereken ayrı bir günlükte bulunur. HTTPS içeriği ve çalışan verimliliği puanlaması bu verilere dahil değildir. SSO/SCIM ve genişletilmiş taslaktaki diğer yöntemler bu uygulanmış sözleşmenin parçası değildir.

Yönetim hataları status, detail ve request_id içeren application/problem+json döndürür. OAuth belirteci verme hataları error alanını kullanır.