Authentication

API keys

A WeGuard API key has three parts:

The example above is fake. Real keys have the same shape: wgk_, a 16-character key id, an underscore and a 43-character secret. The marker and key id together (wgk_<keyId>) form the key’s prefix. The prefix isn’t secret. You can safely log it, and the console and GET /v1/me use it to identify a key.

Sending the key

Send the full key in the Authorization header with the Bearer scheme (case-insensitive). Requests must use HTTPS. The API doesn’t accept keys in query strings or custom headers.

Authorization: Bearer wgk_1a2b3c4d5e6f7a8b_EXAMPLEonlyDoNotUse000000000000000000000000

curl https://api-gw.weguard.ai/core/v1/me \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/me", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/me",
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Creating keys

Account admins create keys in the WeGuard console under Settings → Developer API. Each key has:

• A name of up to 64 characters that describes the integration using it.
• Scopes, which set the data it can read. You can’t change them after you create the key. See Authorization & scopes.
• An expiry: 30, 90, 180 or 365 days, or never.

The console shows the full key once, right after you create it. If you lose it, create a new key. An account can have up to 25 active keys.

Keeping keys safe

Anyone who has a key can read your account’s data within the key’s scopes. Treat keys like passwords:

• Store keys in a secret manager, such as AWS Secrets Manager, Azure Key Vault, Google Secret Manager or HashiCorp Vault, or in your platform’s encrypted environment variables.
• Never put a key in client-side code, such as a web page or a mobile or desktop app, where users can extract it. Call the API from your servers.
• Never commit keys to version control, paste them in tickets or chat, or write them to logs.
• Use one key per integration, with only the scopes it needs, so you can revoke one without affecting others.
• Prefer keys that expire, and rotate long-lived keys regularly.

Rotating a key

Several keys can be active at once, so you can rotate without downtime:

1. Create a new key with the same scopes.
2. Deploy it to your integration.
3. Confirm that the integration uses the new key. For example, call GET /v1/me, or compare last used for both keys in the console.
4. Revoke the old key.

Expiry and revocation

A key stops working at its expiresAt time. After that, requests fail with 401 api_key_expired. An account admin can revoke a key in the console at any time. Revocation takes effect immediately and can’t be undone. Later requests fail with 401 api_key_revoked.

Authentication errors

WeGuard checks credentials in this order and returns the first failure. Every failure is a problem details response with a stable code.

If WeGuard cannot complete these checks because a service it depends on is unavailable, the request fails with 503 service_unavailable and a Retry-After header instead. That isn’t a problem with your key. Retry with backoff.

The WWW-Authenticate header

Every 401 response includes a WWW-Authenticate challenge as described in RFC 6750:

• Bearer realm="WeGuard API" when no credentials were sent.
• Bearer realm="WeGuard API", error="invalid_request" when the header does not use the Bearer scheme.
• Bearer realm="WeGuard API", error="invalid_token" when the key is invalid, revoked or expired.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="WeGuard API", error="invalid_token"
X-Request-Id: req_k3j2h1g0f9e8d7c6b5a4z3y2

{
  "type": "https://weguard.ai/docs/errors#api_key_revoked",
  "title": "API key revoked",
  "status": 401,
  "code": "api_key_revoked",
  "detail": "This API key has been revoked.",
  "instance": "/core/v1/devices",
  "requestId": "req_k3j2h1g0f9e8d7c6b5a4z3y2"
}

Don’t retry 401 and 403 errors automatically. The same key will keep failing. Alert someone on your team, then fix or replace the key.