Meduza Business API

Gestisci aziende, membri, accesso VPN e percorsi tramite la stessa API usata dall’area aziendale.

Prima versione: 169 metodi del contratto attuale — non 169 requisiti completati su 191. La bozza usa percorsi e processi diversi. Matrice completa della prima versione: sono esclusi SSO/SCIM, trasferimento della proprietà, distribuzione del firmware sui router, esportazione delle configurazioni e dati legali delle fatture. notification-channels è solo un inventario legacy: il suo contratto e la consegna email/webhook/in_app sono esclusi dalla prima versione. Sette tipi di avviso sono disponibili in monitoraggio, audit e API; la consegna tramite la separata API dei webhook firmati resta nel perimetro. Router e risorse sono per ora solo inventario; billing-profile conserva solo metadati, senza legame con le fatture.

Autorizzazione e permessi

Percorso base: https://api.meduzavpn.com/api/business/v1. L’interfaccia usa la sessione utente corrente. Per l’automazione, crea un client API nell’area aziendale e salva il segreto al momento del rilascio.

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"

Passa il token ricevuto in Authorization: Bearer TOKEN. Il token vale un’ora e solo all’interno dell’azienda che ha emesso il client. L’accesso viene revocato quando il client viene disattivato o quando l’amministratore che lo ha creato perde i permessi.

Pagamento e fornitura delle VPN

1. Crea l’azienda con POST /organizations da una sessione utente.
2. Ottieni un preventivo con subscription/quotes: numero di VPN, periodo e operazione purchase, renewal o upgrade.
3. Passa quote_id e payment_method: stripe_card a subscription/checkout.
4. La risposta 202 indica che la fattura è in preparazione. Leggi invoices finché non compare payment_url e paga tramite quel link.
5. Dopo la conferma del registro dei pagamenti, l’abbonamento diventa attivo. Crea le VPN con un pricing_id da catalog/vpn-locations e un Idempotency-Key obbligatorio.

Il pacchetto parte da 5 VPN. Prezzo base per VPN: $5.99 al mese o $54.99 all’anno. Sconto sul pacchetto: 5–9 VPN — 5%, 10–99 — 10%, da 100 — 20%. Il ritorno al browser dopo il pagamento non concede l’accesso senza la verifica del pagamento.

Il rinnovo mantiene quantità e periodo. L’ampliamento del pacchetto calcola un supplemento per il periodo residuo. Per eliminare definitivamente un server usa POST /organizations/{organization_id}/vpns/{id}/retire con confirm: true e If-Match. Il posto si libera dopo l’eliminazione confermata; il prezzo dell’abbonamento non cambia. L’assegnazione a un dipendente si passa come member_id; senza di esso la VPN è disponibile all’azienda secondo le assegnazioni di accesso.

Il campo access di PATCH /organizations/{organization_id}/vpns/{id}, con If-Match, stabilisce chi può usare una VPN aziendale. company la apre a tutti i membri dell’azienda il cui ruolo consente la connessione; gli elenchi member_ids e group_ids vengono svuotati. restricted la limita ai dipendenti elencati e ai membri dei gruppi elencati; elenchi vuoti revocano l’accesso a tutti. company insieme a elenchi non vuoti viene rifiutato con 422. Le risposte GET e /me/vpn-grants includono sempre data.access, anche per le VPN create prima dell’introduzione del campo. Una richiesta senza access ma con member_ids o group_ids porta la VPN a restricted, come prima. La VPN dedicata di un dipendente è sempre restricted. I cambi di modalità sono registrati nell’audit come vpn_access_changed; quando l’accesso viene ristretto, le credenziali dei dispositivi che lo hanno perso vengono revocate.

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

Percorsi e insiemi di traffico

Un insieme descrive siti o reti, una regola sceglie l’azione: una VPN specifica, diretto o blocco. Usa paesi e regioni da catalog/traffic-presets. In modalità first-match le regole vengono controllate dall’alto verso il basso, al massimo 128; per «Resto del traffico» il blocco non è disponibile.

Il salvataggio crea una bozza. Esegui la convalida, poi la pubblicazione con If-Match. Controlla policy-deployments: essere in coda ed essere applicato con conferma del dispositivo sono stati diversi. La connessione alla VPN la esegue l’app client.

Ruoli, gruppi e dispositivi

GET /organizations/{id}/roles restituisce i ruoli predefiniti e personalizzati, le definizioni dei permessi e l’indicatore can_manage. Il proprietario crea un ruolo personalizzato partendo da amministratore, dipendente o ruolo finanziario, lasciando solo i permessi necessari. L’assegnazione avviene con PATCH members/{id}: role e custom_role_id. Le modifiche ai permessi valgono anche per i client API creati da quell’utente.

Il ruolo consente azioni nell’area aziendale. group_ids assegna al dipendente le VPN e un pacchetto di instradamento; far parte di un gruppo non dà diritti amministrativi. Il ruolo di proprietario non può essere copiato in uno personalizzato. Un ruolo assegnato a dipendenti non può essere eliminato.

I dispositivi ricevono un display_name, un proprietario e i dati della VPN. PATCH devices/{id} modifica solo il nome, con verifica di If-Match. POST devices/{id}/revocations richiede la revoca; lo stato finale lo conferma il nodo. I propri dispositivi sono disponibili tramite /me/devices. Il campo last_api_ip è l’indirizzo di trasporto dell’API, non della connessione VPN. Nome e modello comunicati dall’app non vengono usati per l’autorizzazione.

Connessioni e registro delle destinazioni

GET /organizations/{id}/employee-analytics mostra le connessioni osservate, i cambi di stato e la cronologia oraria per 7 giorni. Una misurazione mancante non viene sostituita con zero; il numero di sessioni non è il tempo di lavoro del dipendente.

GET /organizations/{id}/activity restituisce le richieste di connessione registrate dal nodo: dominio o IP richiesto, porta, protocollo, ora, decisione, dispositivo e dipendente. Filtri: from, to, member_id, action, search; pagine: cursor e limit. Il dominio è inviato dal client nella richiesta di connessione, non ricavato decifrando l’HTTPS.

La raccolta è disattivata per impostazione predefinita. Il proprietario modifica activity-settings tramite PATCH con {"enabled": true} e If-Match. La lettura richiede activity.read. Con la raccolta attiva l’app mostra un avviso al dipendente; il rilascio della chiave richiede una conferma aggiornata di X-Corporate-Activity-Version dopo la verifica del titolare della chiave. Un client vecchio non riceve la chiave per questa modalità.

La conservazione è limitata a 7 giorni e 100.000 eventi per azienda; il buffer del nodo copre fino a 24 ore. coverage indica l’aggiornamento dei dati, i dispositivi non raggiungibili e le perdite del buffer. Non vengono registrati VPN personali, traffico diretto del dispositivo, blocchi locali prima del nodo, percorsi HTTPS, contenuto delle richieste né valutazioni di produttività. Disattivare la raccolta non ripristina la cronologia mancante e non elimina subito i record già raccolti: vale il periodo di conservazione.

Categorie e tempo di attività di rete

La risposta del registro contiene analysis: distribuzione per categorie, dipendenti e ore, destinazioni principali e il numero di active_minutes. I riepiloghi sono calcolati su tutti gli eventi conservati del periodo scelto, indipendentemente dalla pagina del registro originale. Il filtro category porta agli eventi specifici.

Un minuto attivo è un minuto unico di un dipendente in cui il nodo ha osservato una richiesta. Non è la durata di visita di un sito né del lavoro: conta anche il traffico in background e le categorie possono sovrapporsi nello stesso minuto. Il tempo totale è calcolato separatamente e non è la somma delle categorie.

Il proprietario imposta fino a 64 regole classification_rules nelle impostazioni del registro: dominio e categoria. Valgono anche per i sottodomini e hanno la precedenza sul catalogo integrato. Le destinazioni sconosciute restano in una categoria a parte. Le regole attuali classificano l’intero periodo scelto; la risposta indica la versione della classificazione.

Vengono elaborate le destinazioni delle connessioni aziendali, non il contenuto HTTPS, gli URL completi o il traffico personale. La conferma dell’avviso viene salvata una sola volta per dipendente nell’azienda; cambiare categorie, gruppi o modalità di raccolta non richiede di confermare di nuovo lo stesso avviso. Gli indicatori di copertura incompleta e truncated non vanno interpretati come assenza di attività.

Sottoscrizioni agli eventi

Crea webhooks con un URL HTTPS pubblico sulla porta 443 e gli eventi audit.event, * oppure groups.created, members.updated e altre modifiche alle risorse. Il segreto viene mostrato solo alla creazione o alla rotazione.

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)

Verifica la firma sui byte originali del corpo, l’età ammessa del timestamp e la ripetizione dell’event ID. Durante la rotazione conserva il segreto precedente per gli eventi già in coda. Qualsiasi 2xx è un successo; le altre risposte vengono ritentate a intervalli crescenti, fino a otto tentativi. Cronologia e reinvio manuale sono disponibili tramite deliveries. Le consegne riuscite e annullate sono conservate fino a 30 giorni, al massimo 2.000 per webhook. Coda ed errori sono limitati a 1.000 eventi; in caso di saturazione i più vecchi vengono scartati e il contatore dropped_deliveries segnala la perdita. In tal caso sincronizza lo stato tramite l’API.

La consegna avviene almeno una volta. Oltre alle modifiche fatte tramite l’API, vengono inviate le modifiche confermate di fatture (invoices.updated), abbonamenti (subscriptions.updated), disponibilità delle VPN (vpns.updated) e gli avvisi (alerts.created). Una nuova interrogazione senza cambio di stato non crea un nuovo evento. Non è un flusso di traffico di rete. IP privati, reindirizzamenti e chiamate a servizi interni sono vietati.

Metodi dell’API

Caricamento del contratto…

Pagine e filtri degli elenchi

Per gli elenchi di inventario passa limit=1..200, poi cursor da next_cursor, mantenendo gli altri parametri. Senza limit/cursor i client più vecchi ricevono l’elenco completo: i dati non vengono mai troncati in silenzio. Sono disponibili status, member_id, user_id, vpn_id, search e created_from/created_to (RFC3339, limite inferiore incluso, superiore escluso). L’accesso viene verificato prima del filtro e su ogni pagina. Parametri sconosciuti o ripetuti restituiscono 422. Gli elenchi del registro attività usano un contratto separato. Parametri di ogni metodo.

Cosa copre questa versione

L’audit amministrativo è conservato fino a 90 giorni, al massimo gli ultimi 10.000 eventi per azienda; i record di idempotenza scaduti vengono eliminati. Questa pulizia non elimina fatture e abbonamenti. Gli elenchi di inventario restituiscono items, total e next_cursor; la continuazione compare con limit/cursor espliciti. Senza di essi, la risposta completa resta compatibile con i client più vecchi. Il registro activity supporta separatamente un cursore e i filtri documentati. I segreti non vengono ripetuti nelle risposte dalla cache di idempotenza. La revoca confermata della chiave arriva dal server VPN; la disattivazione di un’appartenenza blocca subito nuovi rilasci.

Il monitoraggio mostra connessioni e carico effettivi. La cronologia delle destinazioni è disponibile tramite un registro separato da attivare esplicitamente. Il contenuto HTTPS e la valutazione della produttività dei dipendenti non fanno parte di questi dati. SSO/SCIM e altri metodi della bozza estesa non fanno parte di questo contratto implementato.

Gli errori di gestione restituiscono application/problem+json con status, detail e request_id. Gli errori di emissione del token OAuth usano il campo error.