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:
- is valid in one project only, chosen when you create it;
- has a role: Can view, Can edit or Can manage (see Projects and people);
- never exceeds either the role you gave it or the role you have in the project today: if your role goes down, so does the key's; if you lose access to the project, the key stops working;
- can expire (in 7, 30 or 90 days, or a year) or not;
- can be a key that only asks: with Requires my approval for every change, every change becomes a request that a person approves (see Plans and change requests). This is the recommended choice for AI agents.
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:
- Name: what it is for (for example CI pipeline, Claude Code);
- Project: the project it works in;
- Role: Can view, Can edit or Can manage (only those you have yourself);
- 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;
- Requires my approval for every change: when on, the key reads whatever its role allows but changes nothing on its own;
- Expires: Never, In 7 days, In 30 days, In 90 days, In a year;
- 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
- One key per program, with the lowest role that does the job. A key that only reads: Can view.
- The secret in an environment variable or a secrets manager, never in code or in a repository.
- An expiry date for test keys.
- First
dry_run, then the real call, for anything that destroys. idempotency_keyon creations, if the program retries requests.