Partner-API
Server-to-server-API voor partners: geef een sleutel uit, lees de configuratie van je etalage en de locaties, maak klanten aan, ken pakketten toe en beheer abonnementslinks vanuit je eigen site of Telegram-bot.
Met de Partner-API bouw je je eigen website, je eigen dashboard of een Telegram-bot bovenop CreateYourVPN.
De API omvat klanten, abonnementen, pakketten en de configuratie van de etalage. Infrastructuur zoals servers, nodes, panels en SSH-gegevens valt buiten het openbare contract.
Alleen server-to-server. Bewaar API-sleutels op je server en neem ze niet op in frontendcode. Verzoeken met browserheaders worden geweigerd met 403 browser_forbidden.
Een sleutel krijgen
Open het dashboard → accountmenu → "API", tabblad "Sleutels".
Geef de sleutel een naam (Telegram-bot, landingspagina) en kies alleen de rechten die hij nodig heeft.
Kies "Sleutel uitgeven" en kopieer de volledige waarde. Het geheim wordt maar één keer getoond, omdat alleen de hash wordt opgeslagen.
Elke partner kan tot 5 actieve sleutels hebben. Om een sleutel te vervangen, geef je een nieuwe uit, werk je de integratie bij en trek je daarna de oude in.
Authenticatie
Stuur de sleutel mee als bearer-token:
curl https://api.createyourvpn.com/api/v1/partner-api/me \
-H "Authorization: Bearer cyv_live_<key_id>_<secret>"X-API-Key: cyv_live_… werkt ook, voor clients waarbij een proxy Authorization al gebruikt.
Een sleutel ziet eruit als cyv_live_<key_id>_<secret>. De eerste helft (key_id) is openbaar: die zie je in het dashboard en die kun je zonder risico aan support doorgeven. De tweede helft is het geheim.
Rechten (scopes)
| Recht | Wat het toestaat |
|---|---|
config:read | De configuratie van de etalage, pakketten, locaties en /me lezen. |
users:read | Klanten, hun abonnementen en verkeer lezen. |
users:write | Klanten aanmaken, pakketten toekennen, abonnementslinks resetten, klanten verwijderen. |
config:read is genoeg voor integraties die alleen gegevens van de etalage lezen. Voeg users:read of users:write alleen toe als de integratie de bijbehorende klantbewerkingen nodig heeft.
API-contract en voorbeelden
Het volledige, uitvoerbare contract staat in de openbare Postman-collectie. Die bevat alle endpoints, rechten, parameters, request bodies, responsvoorbeelden en stabiele foutcodes. De collectie wordt uit het backendcontract gegenereerd en is de actuele bron voor request- en responsschema's.
Verzoeklimieten
Limieten worden per sleutel apart geteld, los van het IP-adres van het verzoek.
- 120 verzoeken/minuut per sleutel in totaal.
- 10 verzoeken/minuut specifiek voor
GET /users.
GET /users heeft een eigen limiet, omdat elk verzoek de volledige klantenlijst laadt. Gebruik voor regelmatige opvragingen GET /users/{id} of zoek op externalId.
Aanbevolen toegangspatroon. Bewaar de CreateYourVPN-klant-ID die je bij het aanmaken terugkrijgt en gebruik GET /users/{id} voor latere opvragingen. Via externalId kun je die aan je eigen ID koppelen.
Idempotentie
Drie bewerkingen vereisen een Idempotency-Key-header: een pakket toekennen, een abonnementslink resetten en een klant verwijderen.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Herhaal je een verzoek met dezelfde sleutel binnen 24 uur, dan krijg je het opgeslagen antwoord terug in plaats van dat de bewerking opnieuw wordt uitgevoerd. Zo ontstaan er geen dubbele wijzigingen wanneer een integratie het na een time-out opnieuw probeert.
Maak één sleutel per zakelijke gebeurtenis (bijvoorbeeld één betaling of één actie) en gebruik die opnieuw bij elke nieuwe poging voor die gebeurtenis.
Loopt de eerste poging nog, of is de uitkomst tijdelijk onbekend, dan antwoordt de API met 409 conflict zonder de bewerking opnieuw uit te voeren. Controleer de huidige toestand van de klant voordat je besluit het opnieuw te proberen.
Gebruik de openbare Postman-collectie hierboven als bron van waarheid voor request- en responsschema's.
Herstellen vanuit een back-up
Twee manieren om uw gebruikers terug te halen: het herstel met één klik in het dashboard dat ze idempotent opnieuw importeert, of een handmatig herstel naar een kale Marzban omdat het bestand het native Marzban-gebruikersformaat is.
Noodtoegang
Een reservemanier om verbinding te maken wanneer een netwerk toelatingslijsten gebruikt en de gewone verbinding geblokkeerd is: maak een videogesprek aan, geef ons de link ervan vanuit je account of per e-mail, en krijg een kant-en-klare verbinding.