API-tokens

Wolkra API-tokens zijn projectgebonden sleutels die beginnen met wk_. Stuur er een mee in de header Authorization: Bearer om de REST API op https://api.wolkra.com/v1 aan te roepen, met lees- of lees/schrijftoegang, een optionele IP-allowlist en een optionele vervaldatum.

Een token aanmaken

1. Schakel in de console over naar het project waar het token toegang toe moet hebben.
2. Open API tokens en kies Create token.
3. Geef het een naam die zegt waar het gebruikt wordt, zoals ci-deploy of monitoring-readonly.
4. Kies het toegangsniveau:
   • Lezen: alleen resources opvragen en bekijken.
   • Lezen/schrijven: ook resources aanmaken, wijzigen en verwijderen.
5. Voeg eventueel een IP-allowlist toe: alleen verzoeken vanaf deze adressen of ranges worden geaccepteerd.
6. Stel eventueel een vervaldatum in.
7. Maak het token aan en kopieer het meteen. Bewaar het als een wachtwoord, bijvoorbeeld in een secretmanager of in de geheime variabelen van je CI.

Je eerste verzoek

Vraag de servers in het project op:

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

Bewaar het token in scripts in een omgevingsvariabele in plaats van in het commando zelf:

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

jq (installeren met sudo apt install -y jq) maakt de JSON-respons leesbaar.

Resources

De API dekt dezelfde resources als de console:

Alle paden zijn relatief aan https://api.wolkra.com/v1. Zo vraag je bijvoorbeeld de volumes op:

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

Acties

Wijzigingen die tijd kosten, zoals een server starten of een volume koppelen, lopen als acties. Controleer de voortgang via /actions voordat je een script laat doorgaan, in plaats van aan te nemen dat de wijziging al klaar is.

Fouten

De API antwoordt met standaard HTTP-statuscodes. Gebruikelijke betekenissen:

Toon de statuscode tijdens het debuggen:

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

Goede gewoonten

• Eén token per toepassing. Een token voor CI, een ander voor monitoring, nog een voor je laptop. Zo trek je er één in zonder de rest te breken.
• Minimale rechten. Gebruik leestokens voor dashboards en monitoring.
• Beperk op adres. Voeg een IP-allowlist toe voor tokens die vanaf vaste servers of CI-runners worden gebruikt.
• Laat tokens verlopen die bedoeld zijn voor een project of een persoon die later vertrekt.
• Commit nooit tokens naar git. Lekt er een uit, verwijder het dan meteen in de console en maak een nieuw token aan.
• Controleer van tijd tot tijd de lijst met tokens en het activiteitenlog van de organisatie.

Een token intrekken

Open API tokens, zoek het token op en verwijder het. Verzoeken met dat token mislukken vanaf dat moment.

Automatisering

Scripts roepen de API rechtstreeks aan via HTTPS. curl, requests in Python, net/http in Go of elke andere HTTP-client werkt. Combineer de API met cloud-init user data om servers bij de eerste start volledig te configureren.

Meer op de productpagina: API. Voor het beveiligen van het account zelf, zie accountbeveiliging.