Jetons d'API

Les jetons d'API Wolkra sont des clés limitées à un projet, qui commencent par wk_. Envoyez-en un dans l'en-tête Authorization: Bearer pour appeler l'API REST à l'adresse https://api.wolkra.com/v1, avec un accès en lecture ou en lecture/écriture, une liste d'IP autorisées facultative et une date d'expiration facultative.

Créer un jeton

1. Dans la console, basculez sur le projet auquel le jeton doit accéder.
2. Ouvrez API tokens et choisissez Create token.
3. Donnez-lui un nom qui indique où il est utilisé, par exemple ci-deploy ou monitoring-readonly.
4. Choisissez le niveau d'accès :
   • Lecture : uniquement lister et consulter les ressources.
   • Lecture/écriture : également créer, modifier et supprimer des ressources.
5. Ajoutez si besoin une liste d'IP autorisées : seules les requêtes provenant de ces adresses ou plages sont acceptées.
6. Définissez si besoin une date d'expiration.
7. Créez le jeton et copiez-le immédiatement. Conservez-le comme un mot de passe, par exemple dans un gestionnaire de secrets ou dans les variables secrètes de votre CI.

Faire votre première requête

Listez les serveurs du projet :

curl -H "Authorization: Bearer wk_…" https://api.wolkra.com/v1/servers

Dans vos scripts, gardez le jeton dans une variable d'environnement plutôt que dans la commande :

export WOLKRA_TOKEN='wk_…'
curl -s -H "Authorization: Bearer $WOLKRA_TOKEN" https://api.wolkra.com/v1/servers | jq .

jq (à installer avec sudo apt install -y jq) met en forme la réponse JSON.

Ressources

L'API couvre les mêmes ressources que la console :

Tous les chemins sont relatifs à https://api.wolkra.com/v1. Par exemple, pour lister les volumes :

curl -s -H "Authorization: Bearer $WOLKRA_TOKEN" https://api.wolkra.com/v1/volumes

Actions

Les modifications qui prennent du temps, comme le démarrage d'un serveur ou l'attachement d'un volume, s'exécutent sous forme d'actions. Vérifiez leur avancement via /actions avant de poursuivre un script, au lieu de supposer que la modification est terminée.

Erreurs

L'API répond avec des codes de statut HTTP standard. Significations habituelles :

Affichez le code de statut pendant le débogage :

curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $WOLKRA_TOKEN" https://api.wolkra.com/v1/servers

Bonnes pratiques

• Un jeton par usage. Un jeton pour la CI, un autre pour la supervision, un autre pour votre ordinateur portable. Vous pouvez en révoquer un sans casser les autres.
• Moindre privilège. Utilisez des jetons en lecture pour les tableaux de bord et la supervision.
• Restriction par adresse. Ajoutez une liste d'IP autorisées aux jetons utilisés depuis des serveurs fixes ou des runners CI.
• Faites expirer les jetons destinés à un projet ponctuel ou à une personne appelée à partir.
• Ne commitez jamais de jetons dans git. Si l'un d'eux fuite, supprimez-le immédiatement dans la console et créez-en un nouveau.
• Passez en revue de temps en temps la liste des jetons et le journal d'activité de l'organisation.

Révoquer un jeton

Ouvrez API tokens, trouvez le jeton et supprimez-le. Les requêtes qui l'utilisent échouent dès lors.

Automatisation

Les scripts appellent l'API directement en HTTPS. curl, requests en Python, net/http en Go ou n'importe quel client HTTP conviennent. Combinez l'API avec les données utilisateur cloud-init pour configurer entièrement vos serveurs dès le premier démarrage.

Plus d'informations sur la page produit : API. Pour sécuriser le compte lui-même, consultez sécurité du compte.