Wolkra

API tokens

Updated

Wolkra API tokens are project-scoped keys that start with wk_. Send one in the Authorization: Bearer header to call the REST API at https://api.wolkra.com/v1, with read or read/write access, an optional IP allow list and an optional expiry date.

Create a token

  1. In the console, switch to the project the token should access.
  2. Open API tokens and choose Create token.
  3. Give it a name that says where it is used, such as ci-deploy or monitoring-readonly.
  4. Choose the access level:
    • Read: list and view resources only.
    • Read/write: also create, change and delete resources.
  5. Optionally add an IP allow list: only requests from these addresses or ranges are accepted.
  6. Optionally set an expiry date.
  7. Create the token and copy it right away. Store it like a password, for example in a secret manager or your CI's secret variables.

Make your first request

List the servers in the project:

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

In scripts, keep the token in an environment variable rather than in the command:

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

jq (install with sudo apt install -y jq) formats the JSON response.

Resources

The API covers the same resources as the console:

Path Resource
/servers cloud servers
/ssh_keys saved SSH keys
/volumes block storage volumes
/networks private networks
/firewalls firewalls
/load_balancers load balancers
/floating_ips floating IPs
/actions actions such as power changes, with their status

All paths are relative to https://api.wolkra.com/v1. For example, to list volumes:

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

Actions

Changes that take time, such as starting a server or attaching a volume, run as actions. Check their progress at /actions before you continue a script, instead of assuming the change is complete.

Errors

The API answers with standard HTTP status codes. Typical meanings:

Status Meaning
401 Missing, wrong or expired token
403 Not allowed, for example a write with a read-only token or a request from outside the allow list
404 The resource does not exist in this project
429 Too many requests; wait and retry
5xx Temporary problem; retry with a delay

Print the status code while you debug:

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

Good practice

  • One token per use. A token for CI, another for monitoring, another for your laptop. Revoke one without breaking the others.
  • Least privilege. Use read tokens for dashboards and monitoring.
  • Restrict by address. Add an IP allow list for tokens used from fixed servers or CI runners.
  • Expire tokens that are meant for a project or a person who will leave.
  • Never commit tokens to git. If one leaks, delete it in the console at once and create a new one.
  • Review the token list and the organization's activity log from time to time.

Revoke a token

Open API tokens, find the token and delete it. Requests with it fail from then on.

Automation

Scripts call the API directly over HTTPS. curl, Python's requests, Go's net/http or any HTTP client works. Combine the API with cloud-init user data to configure servers fully on first boot.

More on the product page: API. For securing the account itself, see account security.

Frequently asked questions

Where is the Wolkra API?

At https://api.wolkra.com/v1. It is a REST API that uses JSON and Bearer token authentication.

What can a token access?

One project. Each token belongs to the project it was created in and has either read or read/write access to its resources.

Can I restrict a token to my servers' addresses?

Yes. Add an IP allow list when you create the token, and requests from any other address are rejected.

Which tools can call the API?

Any HTTP client: curl, Python requests, Go net/http, JavaScript fetch or your CI system's HTTP steps.