Partner-API
Server-til-server-API til partnere: udsted en nøgle, læs butiksfacadens konfiguration og lokationer, opret kunder, tildel planer, og administrer abonnementslinks fra dit eget website eller din Telegram-bot.
Med Partner-API'et kan du bygge dit eget website, dit eget dashboard eller en Telegram-bot oven på CreateYourVPN.
API'et dækker kunder, abonnementer, planer og butiksfacadens konfiguration. Infrastruktur som servere, noder, paneler og SSH-legitimationsoplysninger ligger uden for den offentlige kontrakt.
Kun til server-til-server-brug. Gem API-nøgler på din server, og læg dem ikke i frontend-kode. Anmodninger med browserheadere afvises med 403 browser_forbidden.
Sådan får du en nøgle
Åbn kontrolpanelet → Kontomenu → "API", fanen "Nøgler".
Giv nøglen et navn (Telegram-bot, landingsside), og vælg kun de rettigheder, den har brug for.
Vælg "Udsted nøgle", og kopiér hele værdien. Hemmeligheden vises én gang, fordi kun dens hash gemmes.
Hver partner kan have op til 5 aktive nøgler. For at rotere en nøgle udsteder du en ny, opdaterer integrationen og tilbagekalder derefter den gamle.
Godkendelse
Send nøglen som et 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_… virker også, til klienter, hvor Authorization er optaget af en proxy.
En nøgle ser sådan ud: cyv_live_<key_id>_<secret>. Den første halvdel (key_id) er offentlig: det er den, du ser i kontrolpanelet, og den kan du roligt oplyse til supporten. Den anden halvdel er hemmeligheden.
Rettigheder (scopes)
| Rettighed | Hvad den tillader |
|---|---|
config:read | Læse butiksfacadens konfiguration, planer, lokationer og /me. |
users:read | Læse kunder, deres abonnementer og trafik. |
users:write | Oprette kunder, tildele planer, nulstille abonnementslinks, slette kunder. |
config:read er nok til integrationer, der kun læser data fra butiksfacaden. Tilføj kun users:read eller users:write, når integrationen har brug for de tilsvarende kundeoperationer.
API-kontrakt og eksempler
Den fulde, kørbare kontrakt findes i den offentlige Postman-samling. Den indeholder alle endpoints, rettigheder, parametre, request bodies, svareksempler og stabile fejlkoder. Samlingen genereres fra backend-kontrakten og er den aktuelle kilde til skemaer for anmodninger og svar.
Grænser for anmodninger
Grænserne tælles separat for hver nøgle, uafhængigt af anmodningens IP-adresse.
- 120 anmodninger/minut pr. nøgle i alt.
- 10 anmodninger/minut specifikt for
GET /users.
GET /users har en separat grænse, fordi hver anmodning indlæser hele kundelisten. Til almindelige opslag bruger du GET /users/{id} eller søgning på externalId.
Anbefalet adgangsmønster. Gem det CreateYourVPN-kunde-id, der returneres ved oprettelsen, og brug GET /users/{id} til senere opslag. Du kan knytte det til din egen identifikator via externalId.
Idempotens
Tre operationer kræver headeren Idempotency-Key: tildeling af en plan, nulstilling af et abonnementslink og sletning af en kunde.
curl -X POST .../users/u_9f3a…/grant \
-H "Authorization: Bearer $CYV_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"tariffId":"monthly"}'Gentager du en anmodning med samme nøgle inden for 24 timer, returneres det gemte svar i stedet for at køre operationen igen. Det forhindrer dobbelte ændringer, når en integration prøver igen efter en timeout.
Opret én nøgle for hver forretningshændelse (for eksempel én betaling eller én handling), og genbrug den ved hvert nyt forsøg for den hændelse.
Hvis det første forsøg stadig kører, eller resultatet midlertidigt er ukendt, returnerer API'et 409 conflict uden at udføre operationen igen. Tjek kundens aktuelle tilstand, før du beslutter, om du vil prøve igen.
Brug den offentlige Postman-samling ovenfor som facit for skemaer for anmodninger og svar.
Gendan fra en sikkerhedskopi
To måder at få dine brugere tilbage på: gendannelsen med ét klik i kontrolpanelet, der genimporterer dem idempotent, eller en manuel gendannelse ind i en tom Marzban, da filen er i Marzbans eget brugerformat.
Nødadgang
En reserveløsning til at forbinde, når et netværk bruger hvidlister, og den almindelige forbindelse er blokeret: opret et videoopkald, giv os linket fra din konto eller med e-mail, og få en klar forbindelse.