API reference

Users

The admins and operators who sign in to your account’s console, with their roles and the policies they can access.

Import the whole API:OpenAPI 3.1 Postman collection

Users are the people who sign in to the WeGuard console, not the people using managed devices. The API never returns passwords, MFA secrets, recovery codes, tokens or billing data.

The user object

AttributeDescription

id string: Unique user id.
object string: Always user.
email stringnullable: The email address the user signs in with. null only for malformed legacy records.
firstName stringnullable: First name.
lastName stringnullable: Last name.
role string: Console role, for example customer_admin (full access), group_admin or observer (read-only). New roles may appear. Users without a stored role are reported as customer_admin, because that is how the console treats them.
mfaEnabled boolean: true when the user has completed multi-factor authentication setup, so it is enforced at sign-in. A setup that was started but not finished does not count.
emailVerified boolean: true when the user verified their email address.
ssoLinked boolean: true when the user’s login is linked to single sign-on.
lastLoginAt timestampnullable: When the user last signed in.
createdAt timestamp: When the user was created.
policyScope objectnullable: For roles limited to specific policies, the policies the user can see and manage. null for customer_admin, who can access everything, and when no policy assignment is recorded for the user.
policyScope.allPolicies boolean: true when the user can access every policy. policyIds is then empty.
policyScope.policyIds array of strings: Ids of the policies the user can access.

Example

{
  "id": "5f2a9c3e1b7d4a6f8e0c2b41",
  "object": "user",
  "email": "jane@acme.example",
  "firstName": "Jane",
  "lastName": "Doe",
  "role": "group_admin",
  "mfaEnabled": true,
  "emailVerified": true,
  "ssoLinked": false,
  "lastLoginAt": "2026-10-06T14:02:11Z",
  "createdAt": "2025-02-11T09:00:00Z",
  "policyScope": {
    "allPolicies": false,
    "policyIds": [
      "64ff0a1b2c3d4e5f60718293"
    ]
  }
}

List users

GET/v1/users

Requiresusers:read

Returns the console users of your account, ordered by id (creation order), as a paginated list.

Query parameters

ParameterDescription

role stringoptional: Only return users with this role, for example observer. Matches a lowercase role name exactly: letters and _, at most 64 characters. customer_admin also matches users without a stored role.
limit integeroptionaldefault 25: Maximum number of items to return, from 1 to 100.
cursor stringoptional: The nextCursor from the previous page. Send it unchanged, together with the same filters. See Pagination.
includeTotal booleanoptionaldefault false: Set to true to also return totalCount. It runs an extra count, so request it only when you need it.

Example request

curl "https://api-gw.weguard.ai/core/v1/users?role=group_admin&limit=1" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/users?role=group_admin&limit=1", {
  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/users",
    params={"role": "group_admin", "limit": 1},
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

A list object whose data holds user objects.

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "5f2a9c3e1b7d4a6f8e0c2b41",
      "object": "user",
      "email": "jane@acme.example",
      "firstName": "Jane",
      "lastName": "Doe",
      "role": "group_admin",
      "mfaEnabled": true,
      "emailVerified": true,
      "ssoLinked": false,
      "lastLoginAt": "2026-10-06T14:02:11Z",
      "createdAt": "2025-02-11T09:00:00Z",
      "policyScope": {
        "allPolicies": false,
        "policyIds": [
          "64ff0a1b2c3d4e5f60718293"
        ]
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "YzE6NjUyM2YxYzJhN2I5ZDQwMDEyMzQ1Njc4"
}

Errors

400invalid_parameter
role is not a lowercase role name, limit or includeTotal is invalid, or a parameter was sent twice.
400unknown_parameter
The request includes a query parameter this endpoint does not accept.
400invalid_cursor
The cursor is malformed or was issued for different filters.
403insufficient_scope
The key lacks users:read.

Retrieve a user

GET/v1/users/{userId}

Requiresusers:read

Returns a single console user by id.

Path parameters

ParameterDescription

userId stringrequired: Id of the user. Case-insensitive.

Example request

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

const response = await fetch("https://api-gw.weguard.ai/core/v1/users/5f2a9c3e1b7d4a6f8e0c2b41", {
  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/users/5f2a9c3e1b7d4a6f8e0c2b41",
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

Returns a user object.

200 OK

{
  "id": "5f2a9c3e1b7d4a6f8e0c2b41",
  "object": "user",
  "email": "jane@acme.example",
  "firstName": "Jane",
  "lastName": "Doe",
  "role": "group_admin",
  "mfaEnabled": true,
  "emailVerified": true,
  "ssoLinked": false,
  "lastLoginAt": "2026-10-06T14:02:11Z",
  "createdAt": "2025-02-11T09:00:00Z",
  "policyScope": {
    "allPolicies": false,
    "policyIds": [
      "64ff0a1b2c3d4e5f60718293"
    ]
  }
}

Errors

404resource_not_found
No user with this id exists in your account.
400unknown_parameter
The request includes a query parameter. This endpoint takes none.
403insufficient_scope
The key lacks users:read.

Common errors

Besides the errors listed for each endpoint, any request can fail authentication, exceed the rate limit, ask for a format other than JSON, or fail with a server error. See Errors for the response format and retry guidance.

401missing_credentials
The request has no Authorization header.
401invalid_authorization_header
The Authorization header does not use the Bearer scheme, or has no key after it. The WWW-Authenticate header carries error="invalid_request".
401invalid_api_key
The key is malformed, does not exist, or its secret does not match. The WWW-Authenticate header carries error="invalid_token".
401api_key_expired
The key is past its expiresAt.
401api_key_revoked
An account admin revoked the key. Revocation takes effect immediately and cannot be undone.
403account_inactive
The WeGuard account that owns the key has been deleted or disabled.
406not_acceptable
The Accept header excludes JSON.
429rate_limit_exceeded
The key has used up its request budget. See Rate limits.
500internal_error
An unexpected error occurred on our side.
503service_unavailable
A service WeGuard depends on is temporarily unavailable, or reading the data took longer than the time WeGuard allows for it. This can also happen while your key is being checked, so it can be returned before authentication completes. The response carries Retry-After.

The user object

List users

Query parameters

Example request

Response

Errors

Retrieve a user

Path parameters

Example request

Response

Errors

Common errors

We use cookies