Partner API

Server-to-server API for partners: issue a key, read your storefront config and locations, create clients, grant plans, and manage subscription links from your own site or Telegram bot.

The Partner API lets you build your own site, your own dashboard, or a Telegram bot on top of CreateYourVPN.

The API covers clients, subscriptions, plans, and storefront configuration. Infrastructure such as servers, nodes, panels, and SSH credentials is outside the public contract.

Server-to-server only. Store API keys on your server and do not include them in frontend code. Requests with browser headers are rejected with 403 browser_forbidden.

Getting a key

Open the dashboard → Account menu → "API", the "Keys" tab.

Give the key a name (Telegram bot, landing page) and pick only the permissions it needs.

Select "Issue key" and copy the full value. The secret is shown once because only its hash is stored.

Each partner can have up to 5 active keys. To rotate a key, issue a new one, update the integration, and then revoke the old one.

Authentication

Send the key as a 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_… works too, for clients where Authorization is taken by a proxy.

A key looks like cyv_live_<key_id>_<secret>. The first half (key_id) is public — it is what you see in the dashboard and what you can safely quote to support. The second half is the secret.

Permissions (scopes)

Scope	What it allows
`config:read`	Read your storefront config, plans, locations, and `/me`.
`users:read`	Read clients, their subscriptions and traffic.
`users:write`	Create clients, grant plans, reset subscription links, delete clients.

config:read is sufficient for integrations that only read storefront data. Add users:read or users:write only when the integration needs the corresponding client operations.

The complete, runnable contract lives in the public Postman collection. It contains every endpoint, scope, parameter, request body, response example and stable error code. The collection is generated from the backend contract and is the current source for request and response schemas.

Open the public Postman collection

Explore every endpoint and fork the collection into your workspace.

Rate limits

Limits are counted separately for each key, independently of the request's IP address.

120 requests/minute per key overall.
10 requests/minute for GET /users specifically.

GET /users has a separate limit because each request loads the complete client list. For regular lookups, use GET /users/{id} or search by externalId.

Recommended access pattern. Store the CreateYourVPN client ID returned at creation and use GET /users/{id} for subsequent lookups. You can associate it with your own identifier through externalId.

Idempotency

Three operations require an Idempotency-Key header: granting a plan, resetting a subscription link, and deleting a client.

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

Repeating a request with the same key within 24 hours returns the stored response instead of running the operation again. This prevents duplicate changes when an integration retries after a timeout.

Create one key for each business event (for example, one payment or one action) and reuse it for every retry of that event.

If the first attempt is still running, or its outcome is temporarily unknown, the API returns 409 conflict without performing the operation again. Check the current client state before deciding whether to retry.

Use the public Postman collection above as the source of truth for request and response schemas.