Partner-API
Server-zu-Server-API für Partner: einen Schlüssel ausstellen, die Konfiguration des Schaufensters und die Standorte lesen, Kunden anlegen, Tarife vergeben und Abonnement-Links über die eigene Website oder einen Telegram-Bot verwalten.
Mit der Partner-API kannst du auf CreateYourVPN eine eigene Website, ein eigenes Dashboard oder einen Telegram-Bot aufbauen.
Die API umfasst Kunden, Abonnements, Tarife und die Konfiguration des Schaufensters. Infrastruktur wie Server, Nodes, Panels und SSH-Zugangsdaten gehört nicht zum öffentlichen Vertrag.
Nur für Server-zu-Server-Aufrufe. Speichere API-Schlüssel auf deinem Server und baue sie nicht in Frontend-Code ein. Anfragen mit Browser-Headern werden mit 403 browser_forbidden abgelehnt.
Einen Schlüssel erhalten
Öffne im Dashboard Kontomenü → „API“, Tab „Schlüssel“.
Gib dem Schlüssel einen Namen (Telegram-Bot, Landingpage) und wähle nur die Rechte, die er braucht.
Wähle „Schlüssel ausstellen“ und kopiere den vollständigen Wert. Das Geheimnis wird nur einmal angezeigt, weil nur sein Hash gespeichert wird.
Jeder Partner kann bis zu 5 aktive Schlüssel haben. Um einen Schlüssel zu wechseln, stellst du einen neuen aus, aktualisierst die Integration und widerrufst danach den alten.
Authentifizierung
Sende den Schlüssel 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_… funktioniert ebenfalls, für Clients, bei denen ein Proxy Authorization belegt.
Ein Schlüssel sieht so aus: cyv_live_<key_id>_<secret>. Die erste Hälfte (key_id) ist öffentlich: Sie siehst du im Dashboard, und du kannst sie dem Support bedenkenlos nennen. Die zweite Hälfte ist das Geheimnis.
Rechte (Scopes)
| Recht | Was es erlaubt |
|---|---|
config:read | Konfiguration des Schaufensters, Tarife, Standorte und /me lesen. |
users:read | Kunden, ihre Abonnements und ihren Traffic lesen. |
users:write | Kunden anlegen, Tarife vergeben, Abonnement-Links zurücksetzen, Kunden löschen. |
config:read genügt für Integrationen, die nur Daten des Schaufensters lesen. Füge users:read oder users:write nur hinzu, wenn die Integration die entsprechenden Kundenoperationen braucht.
API-Vertrag und Beispiele
Der vollständige, ausführbare Vertrag liegt in der öffentlichen Postman-Collection. Sie enthält alle Endpunkte, Rechte, Parameter, Request-Bodys, Antwortbeispiele und stabilen Fehlercodes. Die Collection wird aus dem Backend-Vertrag erzeugt und ist die aktuelle Quelle für Request- und Response-Schemas.
Anfragelimits
Limits werden für jeden Schlüssel getrennt gezählt, unabhängig von der IP-Adresse der Anfrage.
- 120 Anfragen/Minute pro Schlüssel insgesamt.
- 10 Anfragen/Minute speziell für
GET /users.
GET /users hat ein eigenes Limit, weil jede Anfrage die vollständige Kundenliste lädt. Für regelmäßige Abfragen nutze GET /users/{id} oder die Suche nach externalId.
Empfohlenes Zugriffsmuster. Speichere die CreateYourVPN-Kunden-ID, die beim Anlegen zurückkommt, und nutze für spätere Abfragen GET /users/{id}. Über externalId kannst du sie mit deiner eigenen Kennung verknüpfen.
Idempotenz
Drei Operationen erfordern einen Idempotency-Key-Header: Tarif vergeben, Abonnement-Link zurücksetzen und Kunden löschen.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Wiederholst du eine Anfrage mit demselben Schlüssel innerhalb von 24 Stunden, kommt die gespeicherte Antwort zurück, statt dass die Operation erneut ausgeführt wird. So entstehen keine doppelten Änderungen, wenn eine Integration nach einem Timeout erneut sendet.
Erzeuge einen Schlüssel pro Geschäftsereignis (zum Beispiel eine Zahlung oder eine Aktion) und verwende ihn für jede Wiederholung dieses Ereignisses.
Läuft der erste Versuch noch oder ist sein Ergebnis vorübergehend unbekannt, antwortet die API mit 409 conflict, ohne die Operation erneut auszuführen. Prüfe den aktuellen Zustand des Kunden, bevor du über eine Wiederholung entscheidest.
Nutze die öffentliche Postman-Collection oben als maßgebliche Quelle für Request- und Response-Schemas.
Aus einem Backup wiederherstellen
Zwei Wege, deine Benutzer zurückzuholen: die Ein-Klick-Wiederherstellung im Dashboard, die sie idempotent erneut importiert, oder eine manuelle Wiederherstellung in ein leeres Marzban, da die Datei im nativen Marzban-Benutzerformat vorliegt.
Notfallzugang
Eine Ersatzverbindung für Netze mit Zulassungslisten, in denen die normale Verbindung blockiert ist: Erstelle einen Videoanruf, gib uns seinen Link aus deinem Konto oder per E-Mail und bekomme eine einsatzbereite Verbindung.