Getting started

Quickstart

Create an API key, check that it works, and read your first devices. It takes about five minutes.

Before you begin

A WeGuard account with at least one enrolled device.
The account admin role, so you can create the API key. If you don’t have it, ask an account admin to create a key for you.
A terminal with curl. For the code examples, Node.js 18 or later, or Python 3 with requests.

1. Create an API key

Sign in to the WeGuard console and open Settings → Developer API.
Select Create API key. Give the key a name that says what will use it, such as CMDB sync, then choose the devices:read scope and an expiry.
Copy the key. You see it only once, because WeGuard stores only a hash of the secret.

Open Settings → Developer API

2. Store the key

Keep the key out of your source code. For this guide, export it in your shell. In production, load it from a secret manager.

bash

export WEGUARD_API_KEY="wgk_1a2b3c4d5e6f7a8b_EXAMPLEonlyDoNotUse000000000000000000000000"

Treat API keys like passwords

Never commit a key to version control or ship it in a browser, mobile or desktop app. Anyone with the key can read your account’s data within its scopes. See Keeping keys safe.

3. Make your first request

GET /v1/me needs no scope. It returns the account and the key behind the request, so it’s the quickest way to check your setup.

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())

200 OK

{
  "object": "me",
  "account": {
    "id": "5f1d7c0e9b1e8a3f2c4d6e8a",
    "name": "Acme Logistics"
  },
  "apiKey": {
    "id": "6701a2b3c4d5e6f708192a3b",
    "name": "CMDB sync",
    "prefix": "wgk_1a2b3c4d5e6f7a8b",
    "scopes": [
      "devices:read"
    ],
    "createdAt": "2026-10-01T10:00:00Z",
    "expiresAt": "2026-12-30T10:00:00Z"
  }
}

A 401 means the key is missing, malformed, unknown, expired or revoked, or the Authorization header does not use the Bearer scheme. The code in the response tells you which. See Errors.

4. List devices

With devices:read, you can list the devices in your account. This example asks for one device to keep the output short. Lists come wrapped in a list object, with the items in data:

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

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

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "6523f1c2a7b9d40012345678",
      "object": "device",
      "platform": "android",
      "name": "Warehouse Scanner 12",
      "model": "SM-T505",
      "manufacturer": "samsung",
      "osVersion": "13",
      "serialNumber": "R9JN30ABCDE",
      "imei": "356938035643809",
      "phoneNumber": null,
      "agentVersion": "6.4.2",
      "policy": {
        "id": "64ff0a1b2c3d4e5f60718293",
        "name": "Kiosk: Scanners"
      },
      "enrollment": {
        "status": "enrolled",
        "enrolledAt": "2026-03-14T08:12:44Z"
      },
      "state": {
        "lost": false,
        "compromised": false,
        "locked": false
      },
      "compliance": {
        "policyCompliant": true,
        "appsCompliant": false
      },
      "tags": {
        "tag1": "Dock 4",
        "tag3": "Night shift"
      },
      "lastSeenAt": "2026-10-07T09:29:51Z",
      "connectivity": {
        "status": "online",
        "thresholdMinutes": 1440
      },
      "createdAt": "2026-03-14T08:10:02Z",
      "details": {
        "deviceIdType": "IMEI",
        "suspended": false,
        "wiped": false,
        "enterpriseEnrolled": true,
        "appliedPolicyVersion": 42,
        "mobileDataUsageBytes": 1288490188,
        "wifiDataUsageBytes": 9663676416,
        "batteryLevel": 87
      }
    }
  ],
  "hasMore": true,
  "nextCursor": "YzE6NjUyM2YxYzJhN2I5ZDQwMDEyMzQ1Njc4"
}

The device object reference describes every field. To filter by platform, use platform=android,ios. To filter by policy, use policyId.

5. Page through results

When hasMore is true, request the next page: pass nextCursor back as cursor and keep the other parameters the same. Use limit=100 to make fewer requests.

# Pass nextCursor from the previous response, with the same filters
curl "https://api-gw.weguard.ai/core/v1/devices?limit=1&cursor=YzE6NjUyM2YxYzJhN2I5ZDQwMDEyMzQ1Njc4" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const BASE_URL = "https://api-gw.weguard.ai/core";
const headers = { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` };

async function* allDevices() {
  let cursor = null;
  do {
    const params = new URLSearchParams({ limit: "100" });
    if (cursor) params.set("cursor", cursor);

    const response = await fetch(`${BASE_URL}/v1/devices?${params}`, { headers });
    const page = await response.json();
    if (!response.ok) throw new Error(`${page.code}: ${page.detail}`);

    yield* page.data;
    cursor = page.hasMore ? page.nextCursor : null;
  } while (cursor);
}

for await (const device of allDevices()) {
  console.log(device.id, device.platform, device.name);
}

import os
import requests

BASE_URL = "https://api-gw.weguard.ai/core"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['WEGUARD_API_KEY']}"

def all_devices():
    params = {"limit": 100}
    while True:
        response = session.get(f"{BASE_URL}/v1/devices", params=params, timeout=30)
        response.raise_for_status()
        page = response.json()
        yield from page["data"]
        if not page["hasMore"]:
            break
        params["cursor"] = page["nextCursor"]

for device in all_devices():
    print(device["id"], device["platform"], device["name"])

Explore in Postman

The Postman collection has every request in the API, grouped by resource, each with an example response. Use it to try the API without writing code.

Postman collection

Every request, grouped by resource, with an example response for each. Set the apiKey variable and send.

JSON · 66 KBDownload

In Postman, select Import and drop in the downloaded file, or paste https://weguard.ai/docs/weguard-developer-api.postman_collection.json.
Open the collection’s Variables tab and paste your key into the Current value of apiKey. The current value stays on your machine. Leave the initial value empty: Postman syncs initial values to your workspace, shares them with anyone who can access the collection, and includes them when you export it.
Open Identity → Retrieve the calling key (GET /v1/me) and select Send. You get the same 200 OK as in step 3.

Optional query parameters are listed in each request’s Params tab but turned off. Select a parameter’s checkbox to send it. For code generators and other tools, use the OpenAPI description.

Next steps

Learn how keys work and how to rotate them in Authentication.
Pick the minimum scopes for your integration in Authorization & scopes.
Handle failures and retries with Errors and Rate limits.
Browse the Devices and Policies reference.