How to Use the Wazuh API: Authenticate, Query Agents, and Automate

The Wazuh API is the scriptable side of your Wazuh server. To use it, send an HTTPS request to TCP port 55000 on the server, authenticate once at /security/user/authenticate to receive a short-lived token, then include that token in an Authorization: Bearer header on every call. It answers in JSON you can filter, log, or wire into other tools.

If the Wazuh dashboard is the storefront you click through, the API is the service entrance. Same data behind it, but a door a script can walk through. Anything you can see in the dashboard (your agents, the manager status, rules, alerts) the API can hand back as plain data, which is what makes it the foundation for automation, custom reports, and integrations. This guide walks the one loop you will use most: log in, ask a question, act on the answer. It assumes you already have a running server; if you do not, start with our full guide to using Wazuh, then come back here.

What is the Wazuh API, and what do you use it for?

The Wazuh API is a REST API, which just means you talk to it with ordinary web requests (a GET to read, a POST to create or authenticate) and it replies in JSON, the same structured text format the rest of the web runs on. It lives on the Wazuh server (the manager) and it is the same interface the dashboard itself uses under the hood, so nothing here is a side channel; it is the front door.

People reach for it when clicking gets old. Common jobs: pull a live inventory of every agent and its status into a spreadsheet or a morning report; script agent enrollment so building a new server also registers it; feed alert or agent data from your SIEM into a ticketing system, a wiki, or your own dashboard; and check the health of the deployment from a monitoring job instead of a human eyeball. The official API documentation lists the full surface, but you can get real work done with two calls.

Before you start: where the API lives

Four facts save you most of the first-time confusion. First, the API listens on TCP port 55000 over HTTPS, on the Wazuh server, and it is enabled by default when you install the server, so there is nothing to turn on. Second, it uses its own account: the default API user is wazuh, and its password is generated when you install the server (treat any default or generated password as temporary and change it straight away). Third, the certificate is self-signed out of the box, so a raw request will complain about the certificate until you trust it; in a lab you pass curl the -k flag to skip that check, but do not do that blindly against production. Fourth, every request is stateless: there is no session cookie, only the token you carry.

Step 1: authenticate and get a token

You cannot call anything useful until you prove who you are, and the API proves it with a JWT (a JSON Web Token, a signed string that says "this request is allowed" without sending your password again). You POST your username and password once to the authenticate endpoint and it hands back the token. The ?raw=true switch is the practitioner's shortcut: it returns the token as plain text, so you can drop it straight into a shell variable.

TOKEN=$(curl -sk -u wazuh:YOUR_PASSWORD -X POST "https://YOUR_SERVER:55000/security/user/authenticate?raw=true")
echo "$TOKEN"

Swap YOUR_PASSWORD and YOUR_SERVER for your own values. We use the wazuh admin account here to keep the example short, but for anything you schedule you should authenticate as a dedicated API user with a read-only role instead of the full admin, for the reasons in the limits section below. Here -s keeps curl quiet, -k accepts the self-signed certificate, and -u passes the user and password. If you prefer to keep the full JSON reply and pull the token out with jq (a small command-line JSON reader you may need to install from your package manager first), this is the same thing the long way:

TOKEN=$(curl -sk -u wazuh:YOUR_PASSWORD -X POST "https://YOUR_SERVER:55000/security/user/authenticate" | jq -r '.data.token')

One thing to burn into memory now, because it is the single most common source of "it worked a minute ago" confusion: the token is valid for 900 seconds, fifteen minutes, by default. After that it expires and you re-authenticate. That is deliberate, and it is why you script the login rather than paste a token by hand.

Step 2: call the API with your token

With the token in $TOKEN, every real call is a normal request that carries it in the Authorization header. The workhorse read is the agent list, which tells you every host reporting in and its state. The ?pretty=true switch just formats the JSON so a human can read it.

curl -sk -H "Authorization: Bearer $TOKEN" "https://YOUR_SERVER:55000/agents?pretty=true"

That is the whole pattern: authenticate once, then reuse $TOKEN on as many calls as you like until it expires. Reading the manager is the same shape, GET /manager/status to confirm each internal service is running and GET /manager/info for the version and build. Learn the request shape once and the rest of the API reference is just different paths.

Worked example: find every agent that stopped reporting

Here is the loop end to end, with a real question a defender asks on a Monday: which of my machines have gone quiet? A disconnected agent is a blind spot, so this is worth automating. You answer it by filtering the same /agents call with status=disconnected.

curl -sk -H "Authorization: Bearer $TOKEN" "https://YOUR_SERVER:55000/agents?status=disconnected&pretty=true"

The server answers with JSON. Trimmed to the parts that matter, one disconnected host looks like this:

{
  "data": {
    "affected_items": [
      {
        "id": "003",
        "name": "legacy-03",
        "ip": "10.0.0.31",
        "status": "disconnected",
        "lastKeepAlive": "2026-07-08T02:14:55Z"
      }
    ],
    "total_affected_items": 1
  },
  "error": 0
}

Now you can read it and act. The affected_items array holds the hosts; total_affected_items is the count. This tells you legacy-03 at 10.0.0.31 last checked in early on 8 July and has been silent since. That is your next task: confirm the box is up, check that ports 1514 and 1515 to the server are open, and restart the agent if the host is healthy. Wrapped in a scheduled job that authenticates, runs this call, and alerts when total_affected_items is above zero, the same three commands become a standing watch on your coverage. If you want the agent to act back on the host once it is reporting again, that is the job of active response, Wazuh's ability to run a command on the host automatically in reaction to an alert.

Where the Wazuh API breaks (the honest limits)

The API is reliable, but a few edges bite everyone once. Knowing them up front saves an afternoon.

• Tokens expire mid-script. Fifteen minutes is short on purpose. A long-running job must re-authenticate when a call starts returning authorization errors, not assume one token lasts the run.

• A security-config change revokes every token. This is the subtle one. If you (or another tool) change the API security settings, all previously issued tokens are invalidated at once, so a script that was working suddenly gets rejected. Re-authenticate and move on.

• Do not leave -k in production. Skipping the certificate check is fine on a lab box, but in production it means you are not verifying you are talking to the real server. Trust the server certificate properly and drop the flag.

• Least privilege is a setting, not a default posture. The API supports role-based access control, so an automation account should get a role that can read agents and nothing more, rather than reusing the full admin user. The securing the API guide covers this.

• Never expose 55000 to the internet. The API is a powerful control surface. Keep it on an internal network or behind a VPN, reachable only from the hosts that need it.

• Results come in pages. A call like /agents returns a bounded page, not necessarily every record, so for large fleets you page through with the limit and offset parameters rather than expecting one response to hold everything.

Where Suriq fits

Everything above is standard, open-source Wazuh, and you can run all of it yourself. Suriq runs managed Wazuh, which means we operate the server, the indexer, and the dashboard for you, and the hardening in the limits section above is our job rather than yours. You still get the data and the ability to automate against your own deployment. If you want the fuller picture of the platform the API sits on, we wrote up why we built Suriq on Wazuh.