Guides

Authorization & scopes

Scopes control what an API key can read. Each endpoint requires specific scopes, and a key only ever sees data from its own account.

Scopes

An account admin chooses a key’s scopes when creating it. They can’t be changed afterwards. A request succeeds only when the key has all the scopes the endpoint requires.

ScopeGrants

devices:read

Read device inventory, hardware, OS, enrollment, policy assignment, connectivity and device status.

GET/v1/devices
GET/v1/devices/{deviceId}
GET/v1/devices/{deviceId}/status
GET/v1/policies/{policyId}/devicesalso requires policies:read

apps:read

Read the applications installed on devices.

GET/v1/devices/{deviceId}/apps

locations:readPersonal data

Read the last reported location and location history of devices.

usage:readPersonal data

Read screen time and app usage of devices.

policies:read

Read policies and their device counts. Listing a policy’s devices also needs devices:read.

GET/v1/policies
GET/v1/policies/{policyId}
GET/v1/policies/{policyId}/devicesalso requires devices:read

account:read

Read account details: plan, license usage and tag labels.

GET/v1/account

users:readPersonal data

Read the account’s console users, their roles and the policies they can access.

GET/v1/users
GET/v1/users/{userId}

audit_logs:readPersonal data

Read the console activity (audit) log.

GET/v1/audit-logs

No scope

Any valid API key.

GET/v1/me

Least privilege

Grant only the scopes an integration uses. A CMDB sync usually needs only devices:read.
Create one key per integration, so you can audit and revoke each one on its own.
Scopes marked personal data expose information about people: device locations, how people use their devices (screen time and app usage), console users’ emails, and console activity with IP addresses. Grant them only where you need them, and handle the data according to your privacy obligations.

Checking a key’s scopes

GET /v1/me needs no scope and returns the key’s scopes. Call it when your integration starts, so it fails fast if the key is missing a scope it needs.

Insufficient scope

When a valid key lacks a required scope, the API responds with 403 and the code insufficient_scope. The WWW-Authenticate header lists the missing scopes, separated by spaces, in its scope parameter:

403 response

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
WWW-Authenticate: Bearer realm="WeGuard API", error="insufficient_scope", scope="locations:read"
X-Request-Id: req_k3j2h1g0f9e8d7c6b5a4z3y2

{
  "type": "https://weguard.ai/docs/errors#insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "This API key is missing the required scope(s): locations:read.",
  "instance": "/core/v1/devices/6523f1c2a7b9d40012345678/location",
  "requestId": "req_k3j2h1g0f9e8d7c6b5a4z3y2"
}

Retrying won’t help. Ask an account admin to create a key with the right scopes in Settings → Developer API, deploy it, and then revoke the old one.

Tenant isolation

Every key belongs to exactly one WeGuard account, and every request is filtered to that account. You can’t read another account’s data, even by id. A resource in a different account looks the same as one that doesn’t exist: the API returns 404 resource_not_found.

If you manage several accounts

Create a key in each account and keep the keys separate in your integration’s configuration.

Changing a key’s scopes

Scopes are fixed for the lifetime of a key. To add or remove a scope:

Create a new key with the scopes you need.
Deploy it to your integration.
Revoke the old key.