API keys
API keys
API keys (prefix wgk_) grant programmatic access to your account: CLI, VS Code extension, CI scripts, or direct calls to the API.
Create a key
Dashboard → Developers → API keys → New key:
| Setting | Role |
|---|---|
| Name | To help you identify it ("CI production", "personal laptop"...) |
| Scopes | What the key is allowed to do (see below) |
| Rate limit | Requests/minute allowed (60 by default) |
| Expiration | Optional, recommended for CI keys |
The full key is shown only once, at creation. Store it in a secrets manager; only its truncated fingerprint remains visible afterward.
Scopes
A scope follows the resource:action format:
projects:read # list and read projects
services:write # deploy, restart, configure
services:* # everything on services
billing:read # read invoices and subscription
* # all rights (avoid outside of tests)
Principle of least privilege: a CI key that only deploys needs just services:write. A monitoring key needs projects:read. Create several narrow keys rather than one broad one.
Using a key
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx"
A key acts on behalf of its owner: it inherits your roles on each project, never more. Its scopes can only restrict, never extend.
Acting for a sub-client (resellers)
A key created with Act for sub-clients enabled (reserved for the owner of an organization) can act on behalf of one of its sub-clients, by adding the X-Act-As-User-Id header:
curl https://api.webgune.cloud/api/v1/projects \
-H "Authorization: Bearer wgk_xxxxxxxxxxxx" \
-H "X-Act-As-User-Id: usr_du_sous_client"
The targeted sub-client must belong to the same organization, otherwise the request fails as if the resource did not exist (404). The key's scopes always apply. Acting for a sub-client does not grant more rights than the key already has.
Audit log
Each key has its own log, viewable from Dashboard → Developers → API keys → log icon, or via GET /api/v1/api-keys/:id/audit-log: the last 100 calls (method, path, return code, duration, and whether the request was made for a sub-client). Useful for spotting a leaking key or a script failing silently.
Limits
- WebSockets excluded: real-time streams (live logs, collaboration) require a browser session: an API key cannot connect to them. The REST snapshot of logs remains accessible.
- An expired or revoked key is refused immediately; revoke any potentially exposed key without hesitation (revocation is instant and has no effect on your other keys).
- Each key has its own rate limit: a runaway script does not exhaust the quota of the others.