Meduza Business API

Kelola perusahaan, anggota, akses VPN, dan rute melalui API yang sama dengan yang dipakai ruang kerja perusahaan.

Rilis pertama: 169 metode kontrak saat ini — bukan 169 dari 191 persyaratan yang selesai. Draf memakai path dan proses yang berbeda. Matriks lengkap rilis pertama: SSO/SCIM, pengalihan kepemilikan, penerapan firmware ke router, ekspor konfigurasi, dan data hukum untuk tagihan dikecualikan. notification-channels hanya inventaris lama: kontraknya serta pengiriman email/webhook/in_app dikecualikan dari rilis pertama. Tujuh jenis peringatan tersedia di pemantauan, audit, dan API; pengiriman melalui webhooks API bertanda tangan yang terpisah tetap termasuk cakupan. Router dan sumber daya untuk saat ini hanya inventaris; billing-profile hanya menyimpan metadata tanpa kaitan dengan tagihan.

Otorisasi dan izin

Path dasar: https://api.meduzavpn.com/api/business/v1. Antarmuka memakai sesi pengguna yang sedang aktif. Untuk otomatisasi, buat klien API di ruang kerja perusahaan dan simpan secret saat diterbitkan.

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"

Kirim token yang diterima di Authorization: Bearer TOKEN. Token berlaku satu jam dan hanya di dalam perusahaan yang menerbitkan klien. Akses dicabut saat klien dinonaktifkan atau saat admin yang membuatnya kehilangan hak.

Pembayaran dan penerbitan VPN

1. Buat perusahaan melalui POST /organizations dari sesi pengguna.
2. Dapatkan penawaran melalui subscription/quotes: jumlah VPN, periode, dan operasi purchase, renewal, atau upgrade.
3. Kirim quote_id dan payment_method: stripe_card ke subscription/checkout.
4. Respons 202 berarti tagihan sedang disiapkan. Baca invoices sampai payment_url muncul, lalu bayar melalui tautan itu.
5. Setelah catatan pembayaran mengonfirmasi pembayaran, langganan menjadi aktif. Buat VPN dengan pricing_id dari catalog/vpn-locations dan Idempotency-Key yang wajib.

Paket mulai dari 5 VPN. Harga dasar per VPN: $5.99 per bulan atau $54.99 per tahun. Diskon paket: 5–9 VPN — 5%, 10–99 — 10%, mulai 100 — 20%. Kembali ke browser setelah membayar tidak memberi akses tanpa verifikasi pembayaran.

Perpanjangan mempertahankan jumlah dan periode. Memperbesar paket menghitung biaya tambahan untuk sisa masa berlaku. Untuk menghapus server secara permanen, gunakan POST /organizations/{organization_id}/vpns/{id}/retire dengan confirm: true dan If-Match. Slot dibebaskan setelah penghapusan dikonfirmasi; harga langganan tidak berubah. Penugasan ke karyawan dikirim sebagai member_id; tanpa itu, VPN tersedia bagi perusahaan sesuai penugasan akses.

Siapa yang dapat memakai VPN perusahaan ditentukan oleh kolom access pada PATCH /organizations/{organization_id}/vpns/{id} dengan If-Match. company membukanya untuk semua anggota perusahaan yang perannya mengizinkan koneksi; daftar member_ids dan group_ids dikosongkan. restricted membatasinya hanya untuk karyawan yang tercantum dan anggota grup yang tercantum; daftar kosong mencabut akses semua orang. company bersama daftar yang tidak kosong ditolak dengan 422. Respons GET dan /me/vpn-grants selalu memuat data.access, termasuk untuk VPN yang dibuat sebelum kolom ini ada. Permintaan tanpa access tetapi dengan member_ids atau group_ids mengubah VPN menjadi restricted, seperti sebelumnya. VPN khusus karyawan selalu restricted. Perubahan mode dicatat di audit sebagai vpn_access_changed; saat akses dipersempit, kredensial perangkat yang kehilangan akses dicabut.

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"}'

Rute dan set lalu lintas

Set menggambarkan situs atau jaringan; aturan memilih tindakan: VPN tertentu, langsung, atau blokir. Gunakan negara dan wilayah dari catalog/traffic-presets. Dalam mode first-match, aturan diperiksa dari atas ke bawah, maksimal 128; untuk “Lalu lintas lainnya” pemblokiran tidak tersedia.

Menyimpan akan membuat draf. Jalankan validasi, lalu publikasikan dengan If-Match. Periksa policy-deployments: masuk antrean dan diterapkan dengan konfirmasi perangkat adalah status yang berbeda. Yang menyambung ke VPN adalah aplikasi klien.

Peran, grup, dan perangkat

GET /organizations/{id}/roles mengembalikan peran bawaan dan khusus, definisi izin, serta penanda can_manage. Pemilik membuat peran khusus berdasarkan peran admin, karyawan, atau keuangan, dengan menyisakan izin yang diperlukan saja. Penugasan dilakukan melalui PATCH members/{id}: role dan custom_role_id. Perubahan izin juga berlaku untuk klien API yang dibuat oleh pengguna tersebut.

Peran mengizinkan tindakan di ruang kerja. group_ids memberi karyawan VPN dan paket perutean; keanggotaan grup tidak memberi hak administratif. Peran pemilik tidak dapat disalin ke peran khusus. Peran yang sudah ditetapkan ke karyawan tidak dapat dihapus.

Perangkat mendapat display_name, pemilik, dan informasi VPN. PATCH devices/{id} hanya mengubah nama, dengan pemeriksaan If-Match. POST devices/{id}/revocations meminta pencabutan; status akhirnya dikonfirmasi oleh node. Perangkat milik sendiri tersedia melalui /me/devices. Kolom last_api_ip adalah alamat transport API, bukan koneksi VPN. Nama dan model yang dilaporkan aplikasi tidak digunakan untuk otorisasi.

Koneksi dan log tujuan

GET /organizations/{id}/employee-analytics menampilkan koneksi yang teramati, perubahan status, dan riwayat per jam selama 7 hari. Pengukuran yang hilang tidak diganti dengan nol; jumlah sesi bukan waktu kerja karyawan.

GET /organizations/{id}/activity mengembalikan permintaan koneksi yang dicatat node: domain atau IP yang diminta, port, protokol, waktu, keputusan, perangkat, dan karyawan. Filter: from, to, member_id, action, search; halaman: cursor dan limit. Domain dikirim klien dalam permintaan koneksi, bukan diperoleh dengan mendekripsi HTTPS.

Pengumpulan nonaktif secara default. Pemilik mengubah activity-settings melalui PATCH dengan {"enabled": true} dan If-Match. Membaca memerlukan activity.read. Saat pengumpulan aktif, aplikasi menampilkan pemberitahuan kepada karyawan; penerbitan kunci memerlukan konfirmasi X-Corporate-Activity-Version yang terbaru setelah pemilik kunci diverifikasi. Klien lama tidak mendapat kunci untuk mode ini.

Penyimpanan dibatasi 7 hari dan 100.000 peristiwa per perusahaan; buffer node menampung hingga 24 jam. coverage melaporkan kebaruan data, perangkat yang tidak terjangkau, dan kehilangan buffer. VPN pribadi, lalu lintas langsung perangkat, pemblokiran lokal sebelum mencapai node, path HTTPS, isi permintaan, dan penilaian produktivitas tidak dicatat. Menonaktifkan pengumpulan tidak memulihkan riwayat yang terlewat dan tidak langsung menghapus catatan yang sudah terkumpul: masa penyimpanan tetap berlaku.

Kategori dan waktu aktivitas jaringan

Respons log berisi analysis: sebaran menurut kategori, karyawan, dan jam, tujuan utama, serta jumlah active_minutes. Ringkasan dihitung dari semua peristiwa tersimpan pada periode yang dipilih, terlepas dari halaman log mentah. Filter category membawa Anda ke peristiwa tertentu.

Satu menit aktif adalah menit unik seorang karyawan saat node mengamati permintaan. Ini bukan lama melihat situs atau lama bekerja: lalu lintas latar belakang ikut dihitung, dan kategori bisa tumpang tindih dalam satu menit. Total waktu dihitung terpisah dan bukan jumlah dari kategori.

Pemilik menetapkan hingga 64 aturan classification_rules di pengaturan pencatatan: domain dan kategori. Aturan berlaku juga untuk subdomain dan lebih diutamakan daripada direktori bawaan. Tujuan yang tidak dikenal tetap di kategori tersendiri. Aturan saat ini mengklasifikasikan seluruh periode yang dipilih; respons menyebutkan versi klasifikasi.

Yang diproses adalah tujuan koneksi perusahaan, bukan isi HTTPS, URL lengkap, atau lalu lintas pribadi. Konfirmasi pemberitahuan disimpan sekali per karyawan di perusahaan; mengubah kategori, grup, atau mode pengumpulan tidak memerlukan konfirmasi ulang atas pemberitahuan yang sama. Penanda cakupan tidak lengkap dan truncated tidak boleh diartikan sebagai tidak ada aktivitas.

Langganan peristiwa

Buat webhooks dengan URL HTTPS publik di port 443 dan peristiwa audit.event, *, atau groups.created, members.updated, dan perubahan sumber daya lainnya. Secret hanya ditampilkan saat dibuat atau dirotasi.

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)

Verifikasi tanda tangan berdasarkan byte asli isi permintaan, usia timestamp yang diizinkan, dan pengulangan event ID. Selama rotasi, simpan secret sebelumnya untuk peristiwa yang sudah masuk antrean. Setiap 2xx dianggap berhasil; respons lain dicoba ulang dengan interval yang makin panjang, hingga delapan kali. Riwayat dan pengiriman ulang manual tersedia melalui deliveries. Pengiriman yang berhasil dan dibatalkan disimpan hingga 30 hari, maksimal 2.000 per webhook. Antrean dan kegagalan dibatasi 1.000 peristiwa; saat penuh, peristiwa terlama dihapus dan penghitung dropped_deliveries melaporkan kehilangan. Dalam hal ini, sinkronkan status melalui API.

Pengiriman dilakukan setidaknya sekali. Selain perubahan melalui API, juga dikirim perubahan yang dikonfirmasi pada tagihan (invoices.updated), langganan (subscriptions.updated), kesiapan VPN (vpns.updated), dan peringatan (alerts.created). Polling ulang tanpa perubahan status tidak membuat peristiwa baru. Ini bukan aliran lalu lintas jaringan. IP privat, pengalihan, dan panggilan ke layanan internal dilarang.

Metode API

Memuat kontrak…

Halaman dan filter daftar

Untuk daftar inventaris, kirim limit=1..200, lalu cursor dari next_cursor, dengan parameter lain tetap sama. Tanpa limit/cursor, klien lama menerima daftar lengkap: data tidak pernah dipotong diam-diam. Tersedia status, member_id, user_id, vpn_id, search, dan created_from/created_to (RFC3339, batas bawah termasuk, batas atas tidak termasuk). Akses diperiksa sebelum pemfilteran dan di setiap halaman. Parameter yang tidak dikenal atau berulang mengembalikan 422. Daftar log aktivitas memakai kontrak tersendiri. Parameter setiap metode.

Yang dicakup versi ini

Audit administratif disimpan hingga 90 hari, maksimal 10.000 peristiwa terakhir per perusahaan; catatan idempotensi yang kedaluwarsa dibersihkan. Pembersihan ini tidak menghapus tagihan dan langganan. Daftar inventaris mengembalikan items, total, dan next_cursor; lanjutan muncul dengan limit/cursor eksplisit. Tanpanya, respons lengkap tetap kompatibel dengan klien lama. Log activity secara terpisah mendukung kursor dan filter yang didokumentasikan. Secret tidak diulang dalam respons dari cache idempotensi. Pencabutan kunci yang terkonfirmasi datang dari server VPN; menonaktifkan keanggotaan langsung mencegah penerbitan baru.

Pemantauan menampilkan koneksi dan beban yang sebenarnya. Riwayat tujuan tersedia melalui log terpisah yang harus diaktifkan secara eksplisit. Isi HTTPS dan penilaian produktivitas karyawan tidak termasuk dalam data ini. SSO/SCIM dan metode lain dari draf yang diperluas tidak termasuk dalam kontrak yang diimplementasikan ini.

Kesalahan pengelolaan mengembalikan application/problem+json dengan status, detail, dan request_id. Kesalahan penerbitan token OAuth memakai kolom error.