API partenaire

API de serveur à serveur pour les partenaires : émettez une clé, lisez la configuration de votre vitrine et les emplacements, créez des clients, attribuez des forfaits et gérez les liens d’abonnement depuis votre site ou votre bot Telegram.

L’API partenaire vous permet de construire votre propre site, votre propre tableau de bord ou un bot Telegram sur CreateYourVPN.

L’API couvre les clients, les abonnements, les forfaits et la configuration de la vitrine. L’infrastructure, comme les serveurs, les nœuds, les panneaux et les identifiants SSH, reste en dehors du contrat public.

Uniquement de serveur à serveur. Conservez les clés API sur votre serveur et ne les incluez pas dans le code frontend. Les requêtes avec des en-têtes de navigateur sont rejetées avec 403 browser_forbidden.

Obtenir une clé

Ouvrez le tableau de bord → menu du compte → « API », onglet « Clés ».

Donnez un nom à la clé (bot Telegram, landing page) et choisissez uniquement les droits dont elle a besoin.

Cliquez sur « Émettre la clé » et copiez la valeur complète. Le secret n’est affiché qu’une fois, car seul son hash est conservé.

Chaque partenaire peut avoir jusqu’à 5 clés actives. Pour remplacer une clé, émettez-en une nouvelle, mettez à jour l’intégration, puis révoquez l’ancienne.

Authentification

Envoyez la clé comme jeton bearer :

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… fonctionne aussi, pour les clients où Authorization est occupé par un proxy.

Une clé ressemble à cyv_live_<key_id>_<secret>. La première moitié (key_id) est publique : c’est elle que vous voyez dans le tableau de bord et que vous pouvez communiquer sans risque au support. La seconde moitié est le secret.

Droits (scopes)

Droit	Ce qu’il permet
`config:read`	Lire la configuration de la vitrine, les forfaits, les emplacements et `/me`.
`users:read`	Lire les clients, leurs abonnements et leur trafic.
`users:write`	Créer des clients, attribuer des forfaits, réinitialiser les liens d’abonnement, supprimer des clients.

config:read suffit pour les intégrations qui lisent seulement les données de la vitrine. N’ajoutez users:read ou users:write que si l’intégration a besoin des opérations correspondantes sur les clients.

Contrat de l’API et exemples

Le contrat complet et exécutable se trouve dans la collection Postman publique. Elle contient chaque endpoint, droit, paramètre, corps de requête, exemple de réponse et code d’erreur stable. La collection est générée à partir du contrat du backend et fait foi pour les schémas de requête et de réponse.

Ouvrir la collection Postman publique

Explorez l’API et dupliquez la collection dans votre espace de travail.

Limites de requêtes

Les limites sont comptées séparément pour chaque clé, indépendamment de l’adresse IP de la requête.

120 requêtes/minute par clé au total.
10 requêtes/minute pour GET /users en particulier.

GET /users a une limite à part, car chaque requête charge la liste complète des clients. Pour les consultations régulières, utilisez GET /users/{id} ou la recherche par externalId.

Méthode d’accès recommandée. Conservez l’ID client CreateYourVPN renvoyé à la création et utilisez GET /users/{id} pour les consultations suivantes. Vous pouvez l’associer à votre propre identifiant via externalId.

Idempotence

Trois opérations exigent un en-tête Idempotency-Key : l’attribution d’un forfait, la réinitialisation d’un lien d’abonnement et la suppression d’un client.

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

Une requête répétée avec la même clé dans les 24 heures renvoie la réponse enregistrée au lieu d’exécuter de nouveau l’opération. Cela évite les modifications en double quand une intégration réessaie après un délai d’attente dépassé.

Créez une clé pour chaque événement métier (par exemple, un paiement ou une action) et réutilisez-la pour chaque nouvelle tentative de cet événement.

Si la première tentative est encore en cours, ou si son résultat est temporairement inconnu, l’API renvoie 409 conflict sans exécuter de nouveau l’opération. Vérifiez l’état actuel du client avant de décider de réessayer.

Utilisez la collection Postman publique ci-dessus comme référence pour les schémas de requête et de réponse.