Partner-API

Server-til-server-API for partnere: utsted en nøkkel, les konfigurasjonen av storefronten og lokasjoner, opprett kunder, tildel planer og administrer abonnementslenker fra ditt eget nettsted eller din Telegram-bot.

Med Partner-API-et kan du bygge ditt eget nettsted, ditt eget dashbord eller en Telegram-bot oppå CreateYourVPN.

API-et dekker kunder, abonnementer, planer og konfigurasjonen av storefronten. Infrastruktur som servere, noder, paneler og SSH-legitimasjon ligger utenfor den offentlige kontrakten.

Bare for server-til-server-bruk. Lagre API-nøkler på serveren din, og ikke ta dem med i frontend-kode. Forespørsler med nettleserheadere avvises med 403 browser_forbidden.

Skaffe en nøkkel

Åpne kontrollpanelet → Kontomeny → «API», fanen «Nøkler».

Gi nøkkelen et navn (Telegram-bot, landingsside), og velg bare rettighetene den trenger.

Velg «Utsted nøkkel», og kopier hele verdien. Hemmeligheten vises én gang, fordi bare hashen lagres.

Hver partner kan ha opptil 5 aktive nøkler. For å rotere en nøkkel utsteder du en ny, oppdaterer integrasjonen og trekker deretter tilbake den gamle.

Autentisering

Send nøkkelen 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_… fungerer også, for klienter der Authorization er opptatt av en proxy.

En nøkkel ser slik ut: cyv_live_<key_id>_<secret>. Den første halvdelen (key_id) er offentlig: det er den du ser i kontrollpanelet, og den kan du trygt oppgi til kundestøtten. Den andre halvdelen er hemmeligheten.

Rettigheter (scopes)

Rettighet	Hva den tillater
`config:read`	Lese konfigurasjonen av storefronten, planer, lokasjoner og `/me`.
`users:read`	Lese kunder, abonnementene deres og trafikk.
`users:write`	Opprette kunder, tildele planer, tilbakestille abonnementslenker, slette kunder.

config:read er nok for integrasjoner som bare leser data fra storefronten. Legg til users:read eller users:write bare når integrasjonen trenger de tilsvarende kundeoperasjonene.

API-kontrakt og eksempler

Den fullstendige, kjørbare kontrakten finnes i den offentlige Postman-samlingen. Den inneholder alle endepunkter, rettigheter, parametere, request bodies, svareksempler og stabile feilkoder. Samlingen genereres fra backend-kontrakten og er den gjeldende kilden for skjemaer for forespørsler og svar.

Åpne den offentlige Postman-samlingen

Utforsk alle endepunkter og fork samlingen til ditt workspace.

Grenser for forespørsler

Grensene telles separat for hver nøkkel, uavhengig av IP-adressen til forespørselen.

120 forespørsler/minutt per nøkkel totalt.
10 forespørsler/minutt for GET /users spesielt.

GET /users har en egen grense fordi hver forespørsel laster hele kundelisten. Til vanlige oppslag bruker du GET /users/{id} eller søk etter externalId.

Anbefalt tilgangsmønster. Lagre CreateYourVPN-kunde-ID-en som returneres ved opprettelse, og bruk GET /users/{id} til senere oppslag. Du kan knytte den til din egen identifikator via externalId.

Idempotens

Tre operasjoner krever headeren Idempotency-Key: tildeling av en plan, tilbakestilling av en abonnementslenke og sletting av en kunde.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Gjentar du en forespørsel med samme nøkkel innen 24 timer, returneres det lagrede svaret i stedet for at operasjonen kjøres på nytt. Det hindrer dupliserte endringer når en integrasjon prøver igjen etter et tidsavbrudd.

Lag én nøkkel for hver forretningshendelse (for eksempel én betaling eller én handling), og bruk den på nytt ved hvert nytt forsøk for den hendelsen.

Hvis det første forsøket fortsatt kjører, eller resultatet er midlertidig ukjent, returnerer API-et 409 conflict uten å utføre operasjonen på nytt. Sjekk kundens nåværende tilstand før du bestemmer deg for om du skal prøve igjen.

Bruk den offentlige Postman-samlingen ovenfor som fasit for skjemaer for forespørsler og svar.