GigakubeWikigigakube.ch →Menu ↓

API keys and the JSON-RPC API

Creating a key for a program or an agent, choosing its role, revoking it, and calling every cloud service with curl.

What an API key is

An API key is a credential for a program (a script, a CI pipeline, your own Terraform, an AI agent) that works without a person in front of it. It starts with gk_ and:

Keys are used on the API (/api/rpc) and on the MCP (/api/mcp, see MCP).

Creating a key

API & agents menu → New API key:

  1. Name: what it is for (for example CI pipeline, Claude Code);
  2. Project: the project it works in;
  3. Role: Can view, Can edit or Can manage (only those you have yourself);
  4. Daily spending limit (CHF): a daily spending cap. The value is saved with the key, but the platform does not enforce it yet: do not rely on it as a safeguard. To limit an agent, use the role and approval;
  5. Requires my approval for every change: when on, the key reads whatever its role allows but changes nothing on its own;
  6. Expires: Never, In 7 days, In 30 days, In 90 days, In a year;
  7. Create key.

Your new API key appears with the secret. Copy it now: you will only see it this once. We only keep a fingerprint: if you lose it, revoke the key and create another. Then I have copied it.

You can have up to 25 keys. In the API keys list you see, for each one, the name, the start of the secret (gk_…), project, role, the approval mark if it only asks, last use and expiry. You also see keys created by others in the projects you own or administer (created by …).

Revoking a key

The bin next to the key → Revoke API key. From that moment every program using it gets an error. It can be revoked by whoever created it, or by someone with Can manage in the key's project.

Revoke it immediately if you think it has fallen into the wrong hands (a repository, a log, a chat).

The API

A single endpoint, JSON-RPC 2.0:

POST https://gigakube.ch/api/rpc
Authorization: Bearer gk_…
Content-Type: application/json

The request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "Cloud/getServerList",
  "params": { "call_data": { } }
}

The method's data goes in params.call_data. You do not choose the project: it is the key's (you can omit tenant; if you include it, it must be the key's).

The response, when it works:

{
  "jsonrpc": "2.0",
  "id": "1",
  "api_version": "1.0",
  "result": {
    "call_data": { "items": [ … ] },
    "user_info": { … }
  }
}

The method's result is in result.call_data (user_info is about the key's holder and you can ignore it). The id always comes back as a string.

If the method refuses:

{
  "jsonrpc": "2.0",
  "id": "1",
  "api_version": "1.0",
  "error": {
    "code": -42402,
    "message": "Ports [22] need an explicit source (CIDR).",
    "data": { "key": "CLOUD_INVALID_REQUEST" }
  }
}

error.data.key is the code to use in your program; message is written for a person. An unexpected error only says System error (ref …): the reference helps us find it, so send it to us.

Before the method runs, the gateway checks the key and answers with an HTTP code:

HTTP error.code Meaning
401 invalid_api_key Key missing, wrong, revoked or expired
403 method_not_allowed_for_keys This method cannot be called with a key (it is panel-only)
429 rate_limited More than 120 requests in one minute with the same key: try again after 60 seconds (Retry-After)

A request can be at most 2 MB.

A first example

export GIGAKUBE_API_KEY=gk_…   # your key

curl -s https://gigakube.ch/api/rpc \
  -H "Authorization: Bearer $GIGAKUBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"Cloud/getStatus","params":{"call_data":{}}}'

With jq, just the servers' names and addresses:

curl -s https://gigakube.ch/api/rpc \
  -H "Authorization: Bearer $GIGAKUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"Cloud/getServerList","params":{"call_data":{}}}' \
  | jq -r '.result.call_data.items[] | "\(.name)\t\(.status)\t\(.public_ip)"'

The quickest way to find the right call: do the thing in the panel in Nerd mode and copy the curl from the call log (The panel).

Long-running operations

Creating a server, a cluster or an import, starting or stopping, are long-running operations: on /api/rpc the response comes back immediately and contains a job ({"job": {"id": …, "status": "queued", …}}). Read it again with Cloud/getJob (job_id) until status is succeeded or failed:

curl -s https://gigakube.ch/api/rpc \
  -H "Authorization: Bearer $GIGAKUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"Cloud/getJob","params":{"call_data":{"job_id":"<job id>"}}}'

To avoid creating the same thing twice if you repeat a request (for example after a network error), put an idempotency_key of your own in call_data: with the same key, the platform creates only one thing. This applies to Cloud/createServer, Cloud/createKubernetesCluster, Cloud/importServer and replications.

Plan first

Every method that changes something accepts "dry_run": true in call_data: it answers with what would happen, without changing anything. A key that requires approval gets a change request instead. See Plans and change requests.

Methods open to API keys

All the panel's Cloud/* methods, plus a few others. The role shown is the minimum.

Project and usage

Method Role What
Tenants/getList viewer The key's project, with the effective role
Tenants/getActivity viewer The activity log (limit 1–500)
Cloud/getStatus viewer Cloud switched on or not, network, role, quota used
Cloud/activate admin Switch on the cloud in the project
Cloud/getCatalog viewer Sizes, images, public networks, Kubernetes versions
Billing/getProjectUsage viewer The project's usage and cost (date_from, date_to as YYYY-MM-DD; without them, the current month)
Cloud/getJob viewer State of a long-running operation (job_id)

Servers, firewall, disks, addresses: Cloud/getServerList, getServer, createServer, serverAction, deleteServer, getConsole, setReverseDns, getFirewall, openPort, updatePort, closePort, getVolumeList, getPublicIpList, getPublicIpPoolList. Details in Virtual machines, Firewall, Networking, Reverse DNS.

L2 networks: Cloud/getNetworkList, getNetwork, createNetwork, deleteNetwork, attachServerToNetwork, detachServerFromNetwork (Networking).

Kubernetes: Cloud/getKubernetesClusterList, getKubernetesCluster, createKubernetesCluster, setKubernetesNodePool, deleteKubernetesNodePool, deleteKubernetesCluster, getKubernetesKubeconfig (Kubernetes).

Imports: Cloud/importServer, getImportList, getImport, startImport, connectImport, cancelImport (Importing a VM).

Attacks: Cloud/getAttackList (Attack protection).

DNS: Dns/getZoneList, Dns/getRecords, Dns/setRecord, Dns/deleteRecord (viewer to read, operator to write); zones: Dns/getProviders, Dns/getDelegation (viewer), Dns/createZone, Dns/deleteZone, Dns/pointTo (operator), Dns/moveZone and the Cloudflare connections Dns/addProvider, Dns/deleteProvider (admin) (DNS).

The account of whoever created the key. These methods act on the account of the person who created the key, not on a project; what counts is the role in the key's project (the weaker of the key's role and its creator's):

Methods Minimum role
Domains/getStatus, Domains/getTldList, Domains/search viewer
SshKey/getList operator
SshKey/create, SshKey/update, SshKey/delete admin
Domains/getList, Domains/get admin
Billing/getSummary, Billing/getUsage, Billing/getTransactions, Billing/getStatements, Billing/downloadInvoice, Wallet/getBalance admin
Domains/register, Domains/setNameservers, Domains/setAutoRenew owner

A key that calls one of these methods without the role gets TENANT_FORBIDDEN (-40465).

Change requests: Cloud/getChangeRequestList, getChangeRequest, decideChangeRequest (Plans and change requests).

Replication between zones, where the zone offers it (otherwise they answer not supported): Cloud/getReplicationList, setReplication, deleteReplication, runReplication, getRestorePointList, restoreReplica. The fields are those of the MCP tools with the same name (MCP).

The following cannot be done with a key: signing up and logging in, profile and password, projects and people (beyond reading), other API keys, top-ups, coupons and the account currency, transferring a domain to another registrar, the assistant. They stay in the panel: they are the things that spend money without a limit or that change who can get in.

Useful error codes

error.data.key Code Meaning
VALIDATION_ERROR -40006 A field is missing or wrong
TENANT_NOT_FOUND -40460 Project does not exist or is not the key's
TENANT_FORBIDDEN -40465 The role is not enough
CLOUD_NOT_AVAILABLE -42400 The cloud is not open for this account
CLOUD_NOT_ACTIVE -42401 The project's cloud is not switched on: Cloud/activate
CLOUD_INVALID_REQUEST -42402 Invalid request: the reason is in message
CLOUD_NOT_FOUND -42403 It does not exist (or does not belong to this project)
CLOUD_CONFLICT -42404 Conflicts with what exists (name already used, cluster not ready…)
CLOUD_QUOTA_EXCEEDED -42405 Project quota exceeded
CLOUD_FORBIDDEN -42406 The role does not allow it (for example a non-web port to the whole internet)
CLOUD_NOT_SUPPORTED -42407 Not available in this zone
CLOUD_UNAVAILABLE -42408 The platform is not responding: nothing has changed, try again
BILLING_NO_CREDIT -42409 Account out of credit: nothing new until you top up
CHANGE_KEY_NO_CREDENTIALS -42436 A key that requires approval cannot open consoles or read kubeconfigs
DNS_ZONE_NOT_FOUND -40431 Zone does not exist
DNS_RECORD_PROTECTED -40436 The apex SOA and NS cannot be changed

For developers: good habits