Partner-API

Server-till-server-API för partner: utfärda en nyckel, läs skyltfönstrets konfiguration och platser, skapa kunder, tilldela planer och hantera prenumerationslänkar från din egen webbplats eller Telegram-bot.

Med Partner-API:t kan du bygga en egen webbplats, en egen kontrollpanel eller en Telegram-bot ovanpå CreateYourVPN.

API:t omfattar kunder, prenumerationer, planer och skyltfönstrets konfiguration. Infrastruktur som servrar, noder, paneler och SSH-uppgifter ligger utanför det offentliga kontraktet.

Endast för server-till-server-anrop. Spara API-nycklar på din server och lägg dem inte i frontend-kod. Förfrågningar med webbläsarheaders avvisas med 403 browser_forbidden.

Skaffa en nyckel

Öppna kontrollpanelen → Kontomeny → "API", fliken "Nycklar".

Ge nyckeln ett namn (Telegram-bot, landningssida) och välj bara de behörigheter den behöver.

Välj "Utfärda nyckel" och kopiera hela värdet. Hemligheten visas en gång, eftersom bara dess hash sparas.

Varje partner kan ha upp till 5 aktiva nycklar. För att rotera en nyckel utfärdar du en ny, uppdaterar integrationen och återkallar sedan den gamla.

Autentisering

Skicka nyckeln som en 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_… fungerar också, för klienter där Authorization är upptagen av en proxy.

En nyckel ser ut så här: cyv_live_<key_id>_<secret>. Den första halvan (key_id) är offentlig: det är den du ser i kontrollpanelen, och den kan du tryggt uppge för supporten. Den andra halvan är hemligheten.

Behörigheter (scopes)

Behörighet	Vad den tillåter
`config:read`	Läsa skyltfönstrets konfiguration, planer, platser och `/me`.
`users:read`	Läsa kunder, deras prenumerationer och trafik.
`users:write`	Skapa kunder, tilldela planer, återställa prenumerationslänkar, radera kunder.

config:read räcker för integrationer som bara läser data från skyltfönstret. Lägg bara till users:read eller users:write när integrationen behöver motsvarande kundoperationer.

API-kontrakt och exempel

Det fullständiga, körbara kontraktet finns i den offentliga Postman-samlingen. Den innehåller alla endpoints, behörigheter, parametrar, request bodies, svarsexempel och stabila felkoder. Samlingen genereras från backend-kontraktet och är den aktuella källan för scheman för förfrågningar och svar.

Öppna den offentliga Postman-samlingen

Utforska alla endpoints och forka samlingen till ditt workspace.

Gränser för förfrågningar

Gränserna räknas separat för varje nyckel, oberoende av förfrågans IP-adress.

120 förfrågningar/minut per nyckel totalt.
10 förfrågningar/minut specifikt för GET /users.

GET /users har en egen gräns eftersom varje förfrågan läser in hela kundlistan. För vanliga uppslag använder du GET /users/{id} eller sökning på externalId.

Rekommenderat åtkomstmönster. Spara CreateYourVPN-kund-ID:t som returneras när kunden skapas och använd GET /users/{id} för senare uppslag. Du kan koppla det till din egen identifierare via externalId.

Idempotens

Tre operationer kräver headern Idempotency-Key: tilldelning av en plan, återställning av en prenumerationslänk och radering av en kund.

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

Upprepar du en förfrågan med samma nyckel inom 24 timmar returneras det sparade svaret i stället för att operationen körs igen. Det förhindrar dubbla ändringar när en integration försöker igen efter en timeout.

Skapa en nyckel för varje affärshändelse (till exempel en betalning eller en åtgärd) och återanvänd den vid varje nytt försök för den händelsen.

Om det första försöket fortfarande pågår, eller om resultatet tillfälligt är okänt, returnerar API:t 409 conflict utan att utföra operationen igen. Kontrollera kundens aktuella tillstånd innan du bestämmer dig för om du ska försöka igen.

Använd den offentliga Postman-samlingen ovan som facit för scheman för förfrågningar och svar.