# API keys

Source : https://webgune.cloud/en-us/docs/cles-api · Mis à jour le 2026-10-27

# API keys

API keys (prefix `wgk_`) grant programmatic access to your account: [CLI](/docs/cli), [VS Code extension](/docs/extension-vscode), CI scripts, or direct calls to the [API](/docs/reference-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

```bash
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](/docs/roles-permissions), 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:

```bash
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.