API partner
API server-to-server per i partner: emetti una chiave, leggi la configurazione della vetrina e le località, crea clienti, assegna piani e gestisci i link di abbonamento dal tuo sito o bot Telegram.
L’API partner ti permette di costruire il tuo sito, la tua dashboard o un bot Telegram su CreateYourVPN.
L’API copre clienti, abbonamenti, piani e configurazione della vetrina. L’infrastruttura, come server, nodi, pannelli e credenziali SSH, resta fuori dal contratto pubblico.
Solo server-to-server. Conserva le chiavi API sul tuo server e non includerle nel codice frontend. Le richieste con header del browser vengono rifiutate con 403 browser_forbidden.
Ottenere una chiave
Apri la dashboard → menu dell’account → «API», scheda «Chiavi».
Dai un nome alla chiave (bot Telegram, landing page) e scegli solo i permessi che le servono.
Premi «Emetti chiave» e copia il valore completo. Il segreto viene mostrato una sola volta, perché ne viene conservato solo l’hash.
Ogni partner può avere fino a 5 chiavi attive. Per ruotare una chiave, emettine una nuova, aggiorna l’integrazione e poi revoca quella vecchia.
Autenticazione
Invia la chiave come token bearer:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"Funziona anche X-API-Key: cyv_live_…, per i client in cui Authorization è occupato da un proxy.
Una chiave ha la forma cyv_live_<key_id>_<secret>. La prima metà (key_id) è pubblica: è quella che vedi nella dashboard e che puoi comunicare al supporto senza rischi. La seconda metà è il segreto.
Permessi (scope)
| Permesso | Cosa consente |
|---|---|
config:read | Leggere la configurazione della vetrina, i piani, le località e /me. |
users:read | Leggere i clienti, i loro abbonamenti e il traffico. |
users:write | Creare clienti, assegnare piani, reimpostare i link di abbonamento, eliminare clienti. |
config:read basta per le integrazioni che leggono solo i dati della vetrina. Aggiungi users:read o users:write solo quando l’integrazione ha bisogno delle operazioni corrispondenti sui clienti.
Contratto dell’API ed esempi
Il contratto completo ed eseguibile si trova nella raccolta pubblica di Postman. Contiene tutti gli endpoint, i permessi, i parametri, i body delle richieste, gli esempi di risposta e i codici di errore stabili. La raccolta è generata dal contratto backend ed è la fonte aggiornata per gli schemi di richiesta e risposta.
Limiti di richieste
I limiti si contano separatamente per ogni chiave, indipendentemente dall’indirizzo IP della richiesta.
- 120 richieste/minuto per chiave in totale.
- 10 richieste/minuto solo per
GET /users.
GET /users ha un limite a parte perché ogni richiesta carica l’elenco completo dei clienti. Per le consultazioni abituali usa GET /users/{id} o la ricerca per externalId.
Schema di accesso consigliato. Conserva l’ID cliente CreateYourVPN restituito alla creazione e usa GET /users/{id} per le consultazioni successive. Puoi associarlo al tuo identificativo tramite externalId.
Idempotenza
Tre operazioni richiedono l’header Idempotency-Key: assegnare un piano, reimpostare un link di abbonamento ed eliminare un cliente.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Ripetere una richiesta con la stessa chiave entro 24 ore restituisce la risposta salvata invece di eseguire di nuovo l’operazione. Così si evitano modifiche doppie quando un’integrazione ritenta dopo un timeout.
Crea una chiave per ogni evento di business (ad esempio un pagamento o un’azione) e riutilizzala per ogni nuovo tentativo di quell’evento.
Se il primo tentativo è ancora in corso, o il suo esito è temporaneamente sconosciuto, l’API risponde 409 conflict senza eseguire di nuovo l’operazione. Controlla lo stato attuale del cliente prima di decidere se ritentare.
Usa la raccolta pubblica di Postman qui sopra come fonte di riferimento per gli schemi di richiesta e risposta.
Ripristina da un backup
Due modi per recuperare i tuoi utenti: il ripristino con un clic dalla dashboard che li reimporta in modo idempotente, oppure un ripristino manuale in un Marzban vuoto, dato che il file è nel formato utente nativo di Marzban.
Accesso di emergenza
Un modo di riserva per connettersi quando la rete usa liste di consentiti e la connessione principale è bloccata: crea una videochiamata, consegnaci il suo link dalla tua area personale o via email e ottieni una connessione pronta all'uso.