Wazuh API Token: Authentication and Setup Guide

The Wazuh server API provides a programmatic interface for managing agents, retrieving security data, configuring Wazuh components, and automating administrative tasks. To protect these API endpoints, Wazuh requires authenticated requests. With the Wazuh server API, authentication is based on JSON Web Tokens (JWTs), which are obtained through the /security/user/authenticate endpoint and then supplied with subsequent requests. For organizations that automate Wazuh administration, integrate Wazuh with external systems, or build scripts around the API, understanding how Wazuh API tokens work is essential.

A correctly configured token allows applications and administrators to authenticate API requests without repeatedly sending a username and password to every endpoint.

Why API Tokens Are Useful for Wazuh Authentication

A Wazuh API token provides a temporary authentication credential that can be presented to protected API endpoints after the initial authentication process.

Instead of including a username and password with every API request, a client first authenticates against the Wazuh API and receives a JWT.

The client can then send that token in the Authorization header of subsequent requests.

For example, an authenticated API request can include:

curl -k -X GET "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

Wazuh documents the JWT-based authentication process as the standard method for accessing protected server API endpoints.

All API endpoints except the authentication endpoints require a valid JWT.

This approach is particularly useful for:

Automation scripts
Configuration-management tools
CI/CD workflows
Custom integrations
Monitoring applications
Security orchestration workflows
Administrative API clients
Automated Wazuh agent management

If you are already automating agent deployment or management, the API token can also be used by scripts that interact with Wazuh agents programmatically.

Wazuh API Tokens vs Username/Password Authentication

It is important to distinguish between the credentials used to obtain a Wazuh API token and the token itself.

The username and password authenticate the user against the Wazuh server API through the /security/user/authenticate endpoint.

After successful authentication, Wazuh returns a JWT.

The JWT is then used as a bearer credential for subsequent API requests.

The typical workflow is:

Provide Wazuh API credentials.
Send a request to /security/user/authenticate.
Receive a JWT.
Store the JWT securely.
Include the JWT in subsequent API requests.
Renew the token when it expires.

This means API tokens reduce the need to repeatedly transmit long-term credentials during an automated API session.

However, a bearer token must itself be protected because anyone who obtains a valid token may be able to use it until it expires or is otherwise invalidated.

This is consistent with broader API-security guidance from OWASP, which notes that bearer tokens should be protected because possession of the token can be sufficient to access the protected resource.

What You Will Learn in This Guide

This guide explains how Wazuh API token authentication works and how to use JWTs when interacting with the Wazuh server API.

You will learn:

What a Wazuh API token is
How Wazuh generates JWT tokens
How the authentication endpoint works
How to authenticate with cURL
How to use a token in API requests
How token expiration works
How Wazuh RBAC affects API access
How to secure API tokens
How to troubleshoot authentication failures
How to use API tokens in automation and scripts

For the official API reference and current authentication procedures, see the Wazuh server API documentation.

What Is a Wazuh API Token?

A Wazuh API token is a JSON Web Token (JWT) issued by the Wazuh server API after a user successfully authenticates.

The token acts as the credential for subsequent requests to protected Wazuh API endpoints.

Wazuh’s documentation specifies that API endpoints, with the exception of authentication endpoints, require a JWT.

The token is supplied using the HTTP Authorization header with the Bearer authentication scheme.

Definition of a Wazuh API Token

In practical terms, a Wazuh API token is a signed JWT containing authentication information associated with the authenticated Wazuh API user.

A token can be obtained with a request similar to:

TOKEN=$(curl -u <WAZUH_API_USER>:<WAZUH_API_PASSWORD> \
  -k -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

When raw=true is specified, Wazuh returns the token as plain text, making it convenient to capture directly into a shell variable.

Without raw=true, the token is returned inside a structured JSON response.

The resulting token can then be used with another API request:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

How Token-Based Authentication Works

Wazuh API token authentication follows a two-stage process.

Stage 1: Authentication

The client sends valid Wazuh API credentials to the authentication endpoint:

POST /security/user/authenticate

Wazuh validates those credentials and generates a JWT when authentication succeeds.

Stage 2: API authorization

The client sends the JWT with subsequent API requests:

Authorization: Bearer <JWT_TOKEN>

Wazuh then validates the token and determines whether the authenticated user has permission to perform the requested operation.

This separation is important because authentication answers who the requester is, while authorization determines what that requester is allowed to do.

How Wazuh API Tokens Authenticate API Requests

A Wazuh API token is passed through the HTTP Authorization header.

For example:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info" \
  -H "Authorization: Bearer $TOKEN"

The Bearer prefix tells the API that the supplied value is a bearer token. Wazuh’s API documentation uses this format for authenticated requests.

The token therefore becomes the credential associated with the API request.

Applications do not need to send the original username and password again for every protected endpoint during the token’s lifetime.

Benefits of Using API Tokens

Using JWT-based authentication provides several practical benefits for Wazuh API integrations.

Automation: Scripts can authenticate once and use the resulting token for multiple API requests.

Reduced credential exposure: Applications can avoid repeatedly transmitting the user’s long-term password to individual API endpoints.

Programmatic access: Tokens make it straightforward to integrate Wazuh with Python, Bash, PowerShell, orchestration platforms, and other applications. Wazuh provides examples for scripting languages and command-line clients.

Expiration: Wazuh supports configurable authentication-token expiration, allowing administrators to limit how long an issued token remains valid.

RBAC integration: API permissions are tied to the authenticated Wazuh user and its authorization context rather than simply granting unrestricted access to anyone who possesses API connectivity.

API Tokens and Least-Privilege Access

A token should not be treated as an automatic administrator credential.

The permissions available to an API client depend on the Wazuh user associated with the authentication process and the permissions assigned through Wazuh’s role-based access control system.

Wazuh exposes RBAC configuration and authorization behavior through its server API.

For automation, create or use an account with only the permissions required for the specific task whenever your Wazuh deployment permits that design.

For example, an automation process that only needs to retrieve agent information should not automatically receive administrative permissions for changing security configuration.

This follows the principle of least privilege: grant an identity only the access necessary to perform its intended function.

For a deeper discussion of permissions and role design, see How to Configure Wazuh RBAC and Mastering Wazuh Security: The Complete Access Control Guide.

Security Considerations

Treat a Wazuh API token as a sensitive credential.

A bearer token can potentially be used by another party if it is exposed.

Avoid placing tokens directly into source code, public repositories, shell history, screenshots, tickets, or application logs.

Recommended practices include:

Use HTTPS for Wazuh API communication.
Protect tokens with appropriate file and process permissions.
Avoid hard-coding tokens into scripts.
Use environment variables or a dedicated secrets-management mechanism where appropriate.
Keep token lifetimes as short as operational requirements allow.
Use least-privilege Wazuh users for automation.
Rotate credentials used to obtain tokens.
Never publish a live token in documentation or troubleshooting output.
Replace self-signed certificates with trusted certificates where appropriate for production environments.

Wazuh recommends securing the server API with HTTPS and changing default API credentials after installation.

Its documentation also recommends using your own certificate rather than relying on the automatically generated self-signed certificate.

How Wazuh API Authentication Works

Understanding the complete authentication flow makes it easier to troubleshoot 401 Unauthorized, expired-token, and permission-related API errors.

At a high level, the process looks like this:

API Client
    |
    | Username + Password
    v
POST /security/user/authenticate
    |
    | JWT Token
    v
Wazuh Server API
    |
    | Authorization: Bearer <TOKEN>
    v
Protected API Endpoint
    |
    | Authentication + Authorization
    v
API Response

Wazuh API Authentication Architecture

The Wazuh server API sits between API clients and Wazuh’s management functionality.

A client might be:

A system administrator using cURL
A Bash script
A Python application
A PowerShell script
An automation platform
The Wazuh Dashboard
A custom integration

The client first authenticates against the Wazuh server API. After receiving a JWT, it uses that token when communicating with protected endpoints.

Wazuh’s API architecture requires authentication for API endpoints and provides RBAC mechanisms to control what authenticated users can access.

Authentication Endpoint and Token Generation

The primary authentication endpoint is:

POST /security/user/authenticate

The default Wazuh server API listens on port 55000 unless it has been configured differently.

A basic cURL example is:

curl -u <WAZUH_API_USER>:<WAZUH_API_PASSWORD> \
  -k -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

To capture the token into an environment variable:

TOKEN=$(curl -u <WAZUH_API_USER>:<WAZUH_API_PASSWORD> \
  -k -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

Wazuh documents this exact authentication pattern for obtaining a JWT from the server API.

If raw=true is omitted, Wazuh returns a JSON response containing the token rather than returning the token directly as plain text.

This can be preferable when an application is already parsing JSON responses.

Bearer Token Authentication

Once the token has been generated, the client includes it in the Authorization header:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

The important part is:

Authorization: Bearer <JWT_TOKEN>

Wazuh requires this JWT on protected API requests.

The same authentication model can be implemented in application code.

For example, Wazuh’s official API examples demonstrate obtaining the JWT and then replacing the initial Basic Authentication header with a Bearer token for subsequent requests.

Token Lifecycle

A Wazuh API token is not necessarily valid indefinitely.

Wazuh exposes the auth_token_exp_timeout security setting, which controls the amount of time in seconds before an authentication token expires and must be renewed.

The setting can be inspected through:

GET /security/config

For example:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/security/config?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Wazuh’s current documentation shows auth_token_exp_timeout as a configurable security setting and provides an example using a 30-minute expiration period.

The practical lifecycle is therefore:

Credentials
    ↓
Authentication request
    ↓
JWT generated
    ↓
JWT used for API requests
    ↓
Token remains valid during its configured lifetime
    ↓
Token expires
    ↓
Client authenticates again
    ↓
New JWT generated

This expiration behavior is particularly important for long-running automation.

Scripts and integrations should be designed to detect an expired token and obtain a new one rather than assuming a token will remain valid permanently.

How the Wazuh API Validates Tokens

When a protected API endpoint receives a request containing a JWT, the Wazuh server API uses the token to authenticate the request before processing the requested operation.

The client provides:

Authorization: Bearer <JWT_TOKEN>

The API then evaluates whether the supplied authentication token is valid and whether the associated user has sufficient permissions for the requested resource.

A valid token therefore does not mean that every API operation is automatically permitted.

Authentication and authorization remain separate stages of the request.

This distinction becomes especially important when troubleshooting API requests that authenticate successfully but return authorization or permission errors.

Relationship Between Wazuh Users, Roles, and API Permissions

Wazuh API tokens are closely connected to the Wazuh identity and authorization model.

The token represents an authenticated Wazuh API user, while that user’s roles and permissions determine which API resources and operations are available.

Conceptually:

Wazuh User
    ↓
Authentication
    ↓
JWT Token
    ↓
User's Authorization Context
    ↓
RBAC Roles / Permissions
    ↓
Allowed API Operations

For example, two users can successfully authenticate and receive valid JWTs but have different access to Wazuh API resources because their roles and permissions differ.

This is why creating a token alone is not sufficient when designing secure Wazuh automation.

You also need to evaluate the privileges of the account that generates the token.

If API access behaves differently between users, review the user’s Wazuh roles and authorization configuration rather than assuming that the token-generation process itself is responsible.

Wazuh API Token Prerequisites

Before generating and using a Wazuh API token, verify that the Wazuh server API is installed, running, reachable, and properly secured.

The API is part of the Wazuh server and provides REST endpoints for tasks such as agent management, manager administration, configuration, RBAC, and security operations.

Wazuh Manager Requirements

The Wazuh server API runs alongside the Wazuh manager.

Therefore, you need access to a functioning Wazuh server before you can authenticate against its API.

For a standard installation, the Wazuh server API configuration is located at:

/var/ossec/api/configuration/api.yaml

The default API port is:

Wazuh documents port 55000 as the default port for the server API, although administrators can change it in api.yaml.

If the manager itself is experiencing problems, resolve those issues before troubleshooting API-token authentication.

Related Guide: Wazuh Manager Scaling Guide

Wazuh API Availability

The Wazuh API must be running and listening on the expected address and port.

You can inspect the API configuration with:

sudo grep -E '^(host|port):' /var/ossec/api/configuration/api.yaml

A typical configuration contains:

host: ['0.0.0.0', '::']
port: 55000

The default configuration allows the API to listen on all available network interfaces.

For production deployments, consider restricting the listening interfaces or placing appropriate network controls in front of the API.

Wazuh specifically documents the host and port parameters as configurable API settings.

Required Administrative Privileges

The credentials used to obtain a Wazuh API token must correspond to a valid Wazuh API user.

However, having a valid token does not automatically grant administrator-level access.

The authenticated user’s roles and permissions determine what that token can access.

Wazuh’s API includes RBAC functionality that controls access to resources and endpoints according to the user’s authorization context.

For example, an account used only to retrieve agent information should not automatically be given permissions to modify users, security configuration, or other administrative resources.

Related Guides:

Network Connectivity to the Wazuh API

The system generating or using the token must be able to reach the Wazuh server API.

Test basic connectivity with:

nc -vz <WAZUH_MANAGER_IP> 55000

Or:

timeout 5 bash -c '</dev/tcp/<WAZUH_MANAGER_IP>/55000' && echo "API port reachable"

If the connection fails, investigate:

Firewall rules
Security groups
Network ACLs
Routing
DNS resolution
Wazuh API listening address
API port configuration
Reverse proxies
Network segmentation

For example, if the API listens only on 127.0.0.1, a remote system will not be able to connect directly to it.

HTTPS and TLS Certificate Considerations

Wazuh enables HTTPS for the server API by default.

If you do not provide your own certificate, the API can generate a self-signed certificate during its first startup.

Wazuh recommends replacing the automatically generated certificate with a trusted certificate for production deployments.

The API’s HTTPS configuration is controlled through /var/ossec/api/configuration/api.yaml:

https:
  enabled: yes
  key: "server.key"
  cert: "server.crt"
  use_ca: false

When testing against a default self-signed certificate, cURL may reject the certificate because it cannot establish a trusted certificate chain.

Wazuh’s documentation uses -k in examples for environments using the default self-signed certificate.

For example:

curl -k https://<WAZUH_MANAGER_IP>:55000/

The -k option should generally be viewed as a troubleshooting or lab convenience rather than a production security recommendation.

In production, configure proper certificate validation instead.

Verifying the Wazuh API Service

On a systemd-based Wazuh server, check the manager service:

sudo systemctl status wazuh-manager

You can also verify that something is listening on port 55000:

sudo ss -lntp | grep 55000

Then test the API locally:

curl -k https://localhost:55000/

If the API is available, you should receive a response from the Wazuh REST API rather than a connection-refused error.

If the API is unavailable, check its logs and the Wazuh manager service before attempting to generate a token.

How to Generate a Wazuh API Token

The Wazuh API token-generation process consists of authenticating with valid Wazuh API credentials and receiving a JWT from the authentication endpoint.

The primary endpoint is:

POST /security/user/authenticate

Wazuh requires a JWT for API endpoints other than the authentication endpoints themselves.

Log In to the Wazuh API

You do not normally log into the API through a browser in the same way you log into the Wazuh Dashboard.

Instead, an API client submits credentials to the authentication endpoint.

For example:

curl -k -X POST \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

Replace:

<WAZUH_API_USER> with the Wazuh API username.
<WAZUH_API_PASSWORD> with its password.
<WAZUH_MANAGER_IP> with the Wazuh server’s IP address or hostname.

Wazuh documents this authentication method as the standard command-line procedure for obtaining a JWT.

Authenticate With Wazuh Credentials

The initial authentication request uses the user’s Wazuh credentials.

For example:

curl -k -X POST \
  -u "wazuh:<PASSWORD>" \
  "https://192.168.1.100:55000/security/user/authenticate?raw=true"

Do not use default credentials in a production deployment. Wazuh recommends changing default API passwords after installation.

If you need to retrieve credentials generated by the Wazuh installation assistant, Wazuh documents the wazuh-install-files.tar archive as one source for the API credentials.

Request an API Token

You can capture the JWT directly into a shell variable:

TOKEN=$(curl -s -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

The raw=true parameter is useful in shell scripts because Wazuh returns the JWT as plain text instead of wrapping it in a JSON response.

Without raw=true, the response contains the token inside the response’s data structure.

Extract the Returned Token

With raw=true, the token can be captured directly:

TOKEN=$(curl -s -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

You can check whether the variable contains a value without printing the entire secret:

if [ -n "$TOKEN" ]; then
    echo "Wazuh API token generated successfully."
else
    echo "Token generation failed."
fi

Avoid using:

echo "$TOKEN"

on production systems because this exposes the complete bearer credential in terminal output.

Wazuh’s own API use-case documentation demonstrates printing the token to verify generation, but that approach should be restricted to controlled testing environments.

Store the Token Securely

Do not store a Wazuh API token directly in source code.

For short-lived shell sessions, an environment variable can be sufficient:

export TOKEN="<JWT_TOKEN>"

For production automation, consider a dedicated secrets-management solution instead.

Also avoid putting the token in:

Git repositories
Configuration files committed to source control
CI/CD logs
Public documentation
Screenshots
Monitoring dashboards
Shell scripts with overly permissive permissions

A JWT is a bearer credential. Anyone who obtains a usable token may be able to make API requests with the permissions associated with its user.

Verify That the Token Works

The simplest verification is to make an authenticated request against the API root:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Wazuh documents this endpoint as a basic way to verify that JWT authentication is working.

A successful response includes API information such as the API version, hostname, and timestamp.

You can also query the agents endpoint:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

If the token is valid and the user has sufficient permissions, Wazuh returns the requested API data.

How to Use a Wazuh API Token

Once you have obtained a JWT, the same token can be supplied to protected API endpoints through the HTTP Authorization header.

The basic format is:

Authorization: Bearer <WAZUH_API_TOKEN>

Wazuh’s API documentation specifies the Bearer format for authenticated requests.

Using cURL

cURL is one of the simplest ways to interact with the Wazuh API because it is available on most Linux systems and can easily send custom HTTP headers.

Assuming the token is stored in $TOKEN:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

For readable JSON output:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

Wazuh’s API request documentation identifies the HTTP method, endpoint URL, and JWT authorization header as the core components of an authenticated API request.

Send a Request With the Authorization: Bearer Header

The critical portion of the request is:

-H "Authorization: Bearer $TOKEN"

The Bearer keyword must appear before the JWT.

For example:

curl -k \
  -H "Authorization: Bearer $TOKEN" \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info"

Do not send the JWT as a Basic Authentication password or as an arbitrary query parameter.

Use the authorization header expected by the Wazuh API.

Query a Wazuh API Endpoint

Once authenticated, you can query different Wazuh API resources depending on the permissions assigned to the user.

For example, retrieve manager information:

curl -k \
  -H "Authorization: Bearer $TOKEN" \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info?pretty=true"

Retrieve agent information:

curl -k \
  -H "Authorization: Bearer $TOKEN" \
  "https://<WAZUH_MANAGER_IP>:55000/agents?pretty=true"

Retrieve an operating-system summary:

curl -k \
  -H "Authorization: Bearer $TOKEN" \
  "https://<WAZUH_MANAGER_IP>:55000/agents/summary/os?pretty=true"

Wazuh provides examples of querying agent information and other API resources using JWT authentication.

Example Authenticated API Request

A complete command-line example looks like this:

#!/bin/bash

WAZUH_API="https://<WAZUH_MANAGER_IP>:55000"

TOKEN=$(curl -s -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "$WAZUH_API/security/user/authenticate?raw=true")

curl -k -X GET \
  "$WAZUH_API/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

For production automation, improve this example by retrieving the username and password from a secure secrets store rather than embedding them in the script.

Handle API Responses

Wazuh API responses are returned as JSON.

The exact structure depends on the endpoint, but Wazuh documents a common response structure containing fields such as data, error, and information about affected or failed items.

For example:

{
  "data": {
    "title": "Wazuh API REST",
    "api_version": "..."
  },
  "error": 0
}

When troubleshooting authentication, pay attention to the HTTP status code as well as the JSON response.

Common situations include:

Response	Likely issue
`200 OK`	Request succeeded
`400 Bad Request`	Invalid request syntax or parameters
`401 Unauthorized`	Missing, invalid, or expired authentication
`403 Forbidden`	Authenticated user lacks required permissions
`404 Not Found`	Endpoint or resource does not exist
`429 Too Many Requests`	API rate limit exceeded
`500 Internal Server Error`	Server-side problem

Wazuh also provides API rate-limiting controls, with max_request_per_minute configurable in the server API configuration.

Using Postman

Postman can be useful when developing or testing Wazuh API integrations because it allows you to inspect requests and responses without repeatedly constructing cURL commands.

Create a new HTTP request and configure:

Method: GET
URL: https://<WAZUH_MANAGER_IP>:55000/agents

If the Wazuh API uses a self-signed certificate in a test environment, Postman’s SSL certificate verification may need to be disabled temporarily.

For production environments, use a trusted certificate instead.

Configure the Authorization Header

In Postman, open the Headers section and add:

Key: Authorization
Value: Bearer <YOUR_WAZUH_API_TOKEN>

Alternatively, Postman’s Authorization interface can be used to configure a Bearer Token.

The resulting HTTP request should contain:

Authorization: Bearer eyJ...

Do not include quotation marks around the token value.

Add the Wazuh API Token

If you store the token as a Postman environment variable, you can use:

Bearer {{wazuh_api_token}}

This is preferable to repeatedly pasting a live token into individual requests.

Protect the Postman environment file and avoid committing it to a source-control repository if it contains live credentials.

Send an Authenticated Request

For example, configure:

GET https://<WAZUH_MANAGER_IP>:55000/manager/info?pretty=true

Then add:

Authorization: Bearer {{wazuh_api_token}}

Click Send.

A successful authentication and authorization should return a JSON response from the Wazuh API.

Troubleshoot Authentication Failures

If Postman returns 401 Unauthorized, verify:

The token has not expired.
The token was copied correctly.
The Authorization header contains Bearer.
There are no extra quotation marks or spaces.
The request is being sent to the correct Wazuh server.
The API port is correct.
The API is running.
The token belongs to a valid Wazuh API user.

If the response is 403 Forbidden, the token may be valid but the associated user may not have permission to access the requested resource.

For broader API authentication problems, see Wazuh API Authentication Failed? Causes and Solutions.

Using Python

Python is useful for Wazuh API integrations that require more sophisticated logic than a shell script.

The requests library can send the JWT through the HTTP authorization header.

A basic example is:

import os
import requests

token = os.environ["WAZUH_API_TOKEN"]

url = "https://<WAZUH_MANAGER_IP>:55000/agents"

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(
    url,
    headers=headers,
    verify=True,
    timeout=30
)

response.raise_for_status()

data = response.json()
print(data)

Wazuh provides official Python examples demonstrating JWT authentication and subsequent API requests.

Store the Token Securely

Rather than placing the token directly in the Python source code, retrieve it from an environment variable:

import os

token = os.environ["WAZUH_API_TOKEN"]

Set the variable outside the source code:

export WAZUH_API_TOKEN="<JWT_TOKEN>"

For production systems, a secrets manager is generally preferable to manually maintained environment variables.

Add the Bearer Token to API Requests

Use the token in the request headers:

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(
    "https://<WAZUH_MANAGER_IP>:55000/manager/info",
    headers=headers,
    timeout=30
)

For a POST or PUT request, the same authorization header can be combined with a JSON request body:

response = requests.post(
    "https://<WAZUH_MANAGER_IP>:55000/<ENDPOINT>",
    headers=headers,
    json=payload,
    timeout=30
)

The endpoint and HTTP method must match the Wazuh API operation you are attempting to perform.

Handle Authentication Errors

Python applications should explicitly handle authentication and authorization failures.

For example:

import requests

try:
    response = requests.get(
        "https://<WAZUH_MANAGER_IP>:55000/agents",
        headers=headers,
        timeout=30
    )

    if response.status_code == 401:
        print("The Wazuh API token is missing, invalid, or expired.")
    elif response.status_code == 403:
        print("The Wazuh user does not have permission for this operation.")
    else:
        response.raise_for_status()

except requests.RequestException as exc:
    print(f"Wazuh API request failed: {exc}")

This distinction is important.

A 401 generally points toward authentication, while a 403 indicates that the request reached an authenticated authorization layer but access to the requested operation was not permitted.

Avoid Hardcoding Tokens in Scripts

Avoid this:

token = "eyJhbGciOi..."

Instead, use:

token = os.environ["WAZUH_API_TOKEN"]

Better still, retrieve the credential through a dedicated secrets-management system when operating at enterprise scale.

Also make sure your application does not accidentally log the authorization header:

print(response.request.headers)

A debugging statement like this can expose the token in application logs.

Using Other Applications

Wazuh API tokens are not limited to cURL, Postman, and Python.

Any application capable of making authenticated HTTPS requests can potentially interact with the Wazuh server API, provided the API user has the required permissions.

Common use cases include:

Automation platforms
Monitoring systems
CI/CD pipelines
SOAR platforms
Custom security applications
Configuration-management systems
Internal administration portals
Scheduled maintenance scripts

Wazuh’s server API supports operations involving agents, managers, clusters, FIM, rules, decoders, RBAC, users, and other Wazuh functionality.

Automation Tools

Automation tools can use JWT authentication to perform repeatable Wazuh operations.

For example, an automation workflow could:

Authenticate
    ↓
Obtain JWT
    ↓
Query Wazuh
    ↓
Evaluate response
    ↓
Perform authorized operation
    ↓
Record result

For agent-focused automation, this can complement your existing deployment workflows.

Related Guides:

Monitoring Systems

Monitoring platforms can use the API to retrieve operational information from Wazuh.

For example, an integration could periodically query:

/manager/info
/agents
/agents/summary/*

and use the returned information to generate monitoring metrics or trigger alerts.

A dedicated low-privilege API user is preferable to using a highly privileged administrative account for monitoring.

CI/CD Pipelines

CI/CD systems can use Wazuh API authentication for automated security workflows.

For example, a deployment pipeline could:

Authenticate against the Wazuh API.
Obtain a short-lived JWT.
Query relevant Wazuh resources.
Perform an authorized API operation.
Discard the token after the job completes.

Store the credentials used by the pipeline in the CI/CD platform’s secret-management facility rather than committing them to the repository.

This approach also makes it easier to rotate credentials without modifying application source code.

Custom Security Integrations

Custom security applications can use the Wazuh API to integrate Wazuh with other security systems.

Potential integrations include:

SOAR platforms
Ticketing systems
Incident-response applications
Threat-intelligence platforms
Custom SOC dashboards
Internal security portals
Automated response systems

For example, an application could query Wazuh for an agent or security event, evaluate the result, and then initiate an authorized response through another system.

When designing these integrations, keep the token’s permissions narrowly scoped and account for token expiration.

Wazuh exposes auth_token_exp_timeout specifically to control how long authentication tokens remain valid.

The most secure architecture is generally to authenticate only when needed, use a short-lived token, perform the required operation, and avoid persisting the bearer token unnecessarily.

Wazuh API Token Permissions and RBAC

A Wazuh API token authenticates a request, but authentication alone does not determine what the requester can do.

The permissions associated with the Wazuh user determine which API resources and operations are available after authentication.

This distinction is critical when deploying API integrations.

A token generated by an administrator account can potentially provide significantly more access than a token generated by a restricted analyst or automation account.

How Wazuh API Permissions Work

The Wazuh API uses authentication and authorization as separate stages of request processing.

The general flow is:

Wazuh credentials
       ↓
Authentication
       ↓
JWT/API token
       ↓
Identify Wazuh user
       ↓
Evaluate roles and permissions
       ↓
Authorize requested API operation
       ↓
Return API response

The token proves that the request has been authenticated. Wazuh then evaluates the user’s authorization context before allowing the requested operation.

For example, a user might successfully authenticate and obtain a valid token but receive a 403 Forbidden response when attempting an operation that their role does not permit.

Wazuh provides role-based access control for managing access to API resources and other protected functionality.

Relationship Between Users, Roles, and Permissions

Think of Wazuh API authorization as a hierarchy:

User
  ↓
Roles
  ↓
Permissions
  ↓
API Resources / Operations

The user is the identity that authenticates against the API.

Roles determine the authorization context associated with that identity, while permissions determine which resources or operations the user can access.

Consequently, two users can generate valid Wazuh API tokens but have completely different capabilities.

For example:

User A
  └── Administrator role
      └── Broad administrative API access

User B
  └── Analyst role
      └── Limited security-data access

User C
  └── Monitoring role
      └── Read-only operational access

This is why API-token security should be considered together with Wazuh RBAC rather than treated as a token-management problem alone.

Related Guides:

Assigning Appropriate Privileges

Before creating a token for automation, identify exactly what the application needs to accomplish.

For example, an application that only needs to retrieve agent information may require read access to agent-related resources.

It does not necessarily need permission to:

Modify Wazuh users
Change RBAC configuration
Modify manager configuration
Create or delete agents
Change security settings
Manage cluster configuration

Start with the smallest practical permission set and expand it only when the integration requires additional capabilities.

This approach makes the consequences of a compromised token substantially easier to contain.

Administrator vs Analyst Access

An administrator token should generally be treated as highly sensitive because it can provide access to administrative API operations.

An analyst account, by comparison, can be designed around security investigation and monitoring requirements rather than infrastructure administration.

For example:

Account type	Typical purpose	Recommended API access
Administrator	Wazuh administration	Broad administrative access
Analyst	Security investigation	Read-focused security access
Monitoring	Health monitoring	Limited read-only access
Automation	Specific workflow	Only permissions required by the workflow

The exact permissions should be determined by your Wazuh RBAC configuration and operational requirements rather than assuming that every account should receive the same privileges.

Least-Privilege API Access

Least privilege means giving an API identity only the permissions required to perform its assigned function.

Suppose a monitoring application needs to query agent status every five minutes.

Creating an administrator account for that application unnecessarily expands the potential impact of a compromised credential.

A better model is:

Monitoring application
        ↓
Dedicated Wazuh user
        ↓
Restricted role
        ↓
Read-only permissions
        ↓
Required API endpoints

This design also improves accountability because API activity can be associated with a specific integration instead of a shared administrator account.

For larger environments, separate API identities should be considered for materially different functions.

Avoiding Excessive Token Permissions

Avoid generating every API token with an administrator identity simply because administrator authentication is easier to configure.

Excessive permissions increase the potential blast radius if:

A token is leaked.
A CI/CD secret is exposed.
An application server is compromised.
Debug logging captures an authorization header.
A developer accidentally publishes credentials.
A token is copied into an insecure environment.

The principle is simple:

The security of an API token is determined not only by how securely the token is stored, but also by what the associated identity is allowed to do.

For sensitive deployments, combine least-privilege roles with short token lifetimes, TLS protection, secure secret storage, and regular permission reviews.

Related Guide: How to Configure Wazuh Field Level Security

How to Test a Wazuh API Token

Testing should verify more than whether a token can authenticate.

A complete test should confirm that the Wazuh API is reachable, the token is valid, permitted operations succeed, and restricted operations are correctly denied.

This provides a practical validation of both authentication and authorization.

Verify the Wazuh API Is Running

Start by checking the Wazuh manager service:

sudo systemctl status wazuh-manager

Then verify that the API is listening on its configured port:

sudo ss -lntp | grep 55000

You can also test basic HTTPS connectivity:

curl -k https://<WAZUH_MANAGER_IP>:55000/

If you receive a connection-refused error, investigate the API service, listener configuration, firewall, and network path before troubleshooting the token itself.

Wazuh documents port 55000 as the default server API port, although it can be changed in the API configuration.

Make an Authenticated API Request

Assuming the token is stored in $TOKEN, send a request to a permitted endpoint:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

You can also test an agent endpoint:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

If the request succeeds, the API has accepted the token and authorized the requested operation.

Confirm the HTTP Response

Do not evaluate authentication based solely on the JSON response body.

Check the HTTP status code as well.

Use cURL’s -i option:

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

You should see a response similar to:

HTTP/1.1 200 OK

A successful request indicates that:

The server is reachable.
The API endpoint exists.
The authentication header was accepted.
The token is valid.
The user is authorized for the requested operation.

Test Access to Permitted Endpoints

Testing a known permitted endpoint confirms that the token works for its intended purpose.

For example:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

If the account was specifically created for read-only monitoring, verify all of the endpoints the monitoring application actually requires.

Do not stop after testing only one endpoint if the integration depends on several API resources.

Create a small validation matrix if necessary:

Endpoint	Expected result
Permitted read endpoint	`200 OK`
Another permitted endpoint	`200 OK`
Restricted administrative endpoint	`403 Forbidden`
Missing token	`401 Unauthorized`
Invalid token	`401 Unauthorized`

This gives you evidence that both authentication and RBAC are behaving as expected.

Test Access to Restricted Endpoints

A properly configured least-privilege token should not be able to perform operations outside its assigned permissions.

For example, if the account is intentionally restricted, test an administrative endpoint that should not be available to it.

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/security/config" \
  -H "Authorization: Bearer $TOKEN"

The exact result depends on the user’s Wazuh permissions.

If the user is not authorized, a 403 Forbidden response is an expected and desirable result.

This test is particularly useful after creating or modifying Wazuh roles because it verifies that restrictions are actually enforced rather than merely documented.

Check Wazuh API Logs

If authentication behaves unexpectedly, inspect the Wazuh server logs.

A useful starting point is:

sudo tail -f /var/ossec/logs/api.log

You can also search the log for authentication-related entries:

sudo grep -iE "auth|token|401|403|error" \
  /var/ossec/logs/api.log

The exact available log information can vary according to Wazuh version and configuration, so use the API logs together with the HTTP status code and response body.

Be careful when sharing logs externally. Authentication failures and debugging output can sometimes contain information that should not be publicly disclosed.

Common Wazuh API Token Errors

Most Wazuh API token problems fall into a few categories: authentication failures, authorization failures, malformed requests, token-generation failures, and TLS/connectivity problems.

The most useful first step is to determine whether the request reached the API and, if so, what HTTP status code was returned.

401 Unauthorized

A 401 Unauthorized response generally indicates that the API could not authenticate the request.

For example:

HTTP/1.1 401 Unauthorized

Common causes include:

Invalid token
Expired token
Missing Authorization header
Incorrect Bearer syntax
Invalid username or password during token generation
Authentication configuration problems

Start by obtaining a fresh token and testing it against a simple API endpoint.

TOKEN=$(curl -s -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

Then:

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info" \
  -H "Authorization: Bearer $TOKEN"

If the newly generated token works, the previous token was likely expired, invalid, or incorrectly stored.

Invalid or Expired Token

Wazuh authentication tokens have a configurable expiration period.

If a previously working token suddenly begins returning 401 Unauthorized, token expiration should be one of the first things you investigate.

Obtain a new token:

TOKEN=$(curl -s -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

Then retry the request.

For long-running applications, implement token renewal rather than storing one JWT indefinitely.

Missing Authorization Header

A token stored correctly in an environment variable is useless if the application never sends it to the API.

Incorrect:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/agents"

Correct:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

Check the actual outgoing request generated by your application or HTTP client.

Incorrect Bearer Token Format

The Wazuh API expects the JWT in the Authorization header using the Bearer scheme.

Correct:

Authorization: Bearer eyJ...

Common mistakes include:

Authorization: eyJ...

or:

Authorization: Token eyJ...

or:

Authorization: Bearer "eyJ..."

The safest approach is to construct the header exactly as documented:

Authorization: Bearer <JWT>

Wazuh’s API documentation specifies the Bearer authentication format for authenticated requests.

Authentication Configuration Problems

If fresh tokens consistently fail, investigate the Wazuh API configuration.

Check:

sudo nano /var/ossec/api/configuration/api.yaml

Review relevant settings, including:

API listener address
API port
HTTPS configuration
Certificate configuration
Authentication settings
Token expiration configuration
RBAC-related settings

After configuration changes, restart the Wazuh manager if required by the specific setting:

sudo systemctl restart wazuh-manager

Then verify that the API is listening again before generating another token.

403 Forbidden

A 403 Forbidden response is different from a 401 Unauthorized response.

A 401 generally indicates an authentication problem.

A 403 generally means that the request was authenticated but the user is not authorized to perform the requested operation.

For example:

HTTP/1.1 403 Forbidden

Possible causes include:

User lacks required permissions
RBAC restrictions
Insufficient role privileges
Attempting to access an administrative endpoint with an analyst account

User Lacks Required Permissions

If a token works for one endpoint but returns 403 for another, compare the permissions required by the two operations.

For example:

GET /agents
       ↓
Allowed

Administrative operation
       ↓
403 Forbidden

This can be expected behavior when the API user was intentionally configured with restricted privileges.

Do not immediately solve a 403 by granting administrator access.

First determine which specific permission is missing.

RBAC Restrictions

Wazuh RBAC can restrict access to resources even when authentication succeeds.

This is one reason API-token troubleshooting should always distinguish authentication from authorization.

Check:

Which Wazuh user generated the token
Which roles are associated with that user
Which permissions those roles provide
Whether the requested endpoint falls within those permissions

Related Guide: Troubleshooting Wazuh RBAC

Insufficient Role Privileges

A user may have a valid role but insufficient privileges for a particular API operation.

For example:

Authentication: SUCCESS
Token: VALID
Endpoint: VALID
Authorization: DENIED
Result: 403

In this situation, generating another token for the same user will usually not solve the problem because the new token will still represent the same user’s authorization context.

Instead, review the role assignment and permissions.

400 Bad Request

A 400 Bad Request generally indicates that the API received the request but could not process it because the request itself was invalid.

Potential causes include:

Incorrect API request format
Invalid authentication parameters
Missing required parameters
Malformed JSON
Invalid query parameters
Incorrect HTTP method

For example, an endpoint that expects a particular request body may reject malformed JSON before the requested operation can be processed.

Incorrect API Request Format

Verify that:

The HTTP method is correct.
The URL is correct.
Query parameters are correctly encoded.
Required headers are present.
JSON is valid.
Required request fields are included.

For example:

curl -k -X GET \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

Compare the request with the Wazuh API documentation for the specific endpoint.

Invalid Authentication Parameters

During token generation, ensure that the authentication request uses the correct endpoint and credentials:

curl -k -X POST \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

A malformed authentication URL or incorrect parameters can prevent token generation before the bearer-token stage is even reached.

Malformed Request

For POST and PUT operations, inspect the request body carefully.

A malformed JSON document such as:

{
  "field": "value"

will not be accepted as valid JSON.

Use tools such as jq to validate JSON before sending complex requests:

cat payload.json | jq .

Then submit the validated document to the API.

Token Generation Fails

Token generation occurs before the JWT can be used with protected endpoints.

If the authentication endpoint does not return a token, investigate the credentials, API service, configuration, and TLS connection separately.

Incorrect Wazuh Credentials

First verify that the username and password are correct.

Test the authentication request directly:

curl -k -i \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate"

If authentication fails, confirm:

Username
Password
API hostname/IP
API port
Authentication endpoint
Wazuh API availability

Avoid repeatedly guessing passwords because authentication protections and rate limits can affect repeated requests.

API Service Problems

If the API cannot be reached, token generation cannot succeed.

Check:

sudo systemctl status wazuh-manager

Then:

sudo ss -lntp | grep 55000

And:

curl -k -i https://localhost:55000/

If the local API request fails, investigate the Wazuh server before changing credentials or RBAC settings.

Configuration Errors

Review:

/var/ossec/api/configuration/api.yaml

Look for configuration errors involving:

Port
Host address
HTTPS
Certificates
Authentication
Token expiration
API settings

After making a configuration change, verify the service status and API listener before retesting authentication.

TLS Issues

TLS problems can prevent a client from reaching the authentication endpoint even when the Wazuh API itself is healthy.

A common example is a self-signed certificate that the client does not trust.

For testing:

curl -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

The -k option disables certificate verification in cURL.

Do not use this as the preferred production solution.

Instead, configure a trusted certificate chain and allow the client to verify the Wazuh API certificate normally.

You can inspect the TLS handshake with:

openssl s_client \
  -connect <WAZUH_MANAGER_IP>:55000 \
  -servername <WAZUH_MANAGER_HOSTNAME>

Look for certificate-chain problems, hostname mismatches, expired certificates, and other TLS verification failures.

Related Guide: How to Fix Wazuh Certificate Errors

When troubleshooting Wazuh API token generation, work through the layers in order:

Network connectivity
        ↓
API service
        ↓
HTTPS/TLS
        ↓
Authentication credentials
        ↓
JWT generation
        ↓
Bearer token
        ↓
RBAC authorization
        ↓
API endpoint permissions

This prevents authentication problems from being confused with network, TLS, or authorization problems and makes it much easier to identify the actual cause.

How to Troubleshoot Wazuh API Token Authentication

When Wazuh API token authentication fails, troubleshoot the request in layers rather than immediately generating another token.

A 401 Unauthorized can indicate an invalid or expired JWT, while a 403 Forbidden usually points to authorization or RBAC restrictions. Connectivity, TLS, reverse-proxy, and version issues can also prevent a request from reaching the authentication layer correctly.

Check Wazuh API Service Status

Start by verifying that the Wazuh manager service is running:

sudo systemctl status wazuh-manager

If the service is stopped, restart it:

sudo systemctl restart wazuh-manager

Then confirm that the API is listening on its configured port:

sudo ss -lntp | grep 55000

Port 55000 is the default Wazuh server API port, although it can be changed in the API configuration.

If nothing is listening on the expected port, troubleshoot the Wazuh service before investigating JWTs.

Review API Logs

The Wazuh API log can provide useful information about authentication and API failures.

Start by inspecting recent entries:

sudo tail -n 100 /var/ossec/logs/api.log

To monitor the log while reproducing the problem:

sudo tail -f /var/ossec/logs/api.log

You can search for authentication-related messages:

sudo grep -iE "auth|token|401|403|error" /var/ossec/logs/api.log

Look for evidence of:

Authentication failures
Invalid requests
Authorization failures
Configuration errors
TLS problems
Unexpected API errors

Avoid posting complete production logs publicly because they may contain infrastructure details or other sensitive information.

Verify the Authentication Endpoint

The standard Wazuh authentication endpoint is:

POST /security/user/authenticate

Test it directly:

curl -k -i -X POST \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate"

For a token that can be captured directly into a variable, use raw=true:

curl -s -k -X POST \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

If this request cannot generate a token, there is no reason to troubleshoot the bearer-token portion of the workflow yet.

Confirm the Token Format

A Wazuh API token is supplied as a JWT through the HTTP Authorization header.

The expected format is:

Authorization: Bearer <JWT_TOKEN>

For cURL:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

Common formatting mistakes include:

Authorization: <TOKEN>

Authorization: Token <TOKEN>

or accidentally sending quotation marks as part of the header value.

If you are using an environment variable, verify that it is populated without printing the secret itself:

if [ -n "$TOKEN" ]; then
    echo "Token is present"
else
    echo "Token is missing"
fi

Wazuh documents the Bearer-token format for authenticated API requests.

Check User Permissions

A valid token does not guarantee access to every Wazuh API endpoint.

If you receive:

401 Unauthorized

investigate authentication.

If you receive:

403 Forbidden

investigate authorization and permissions.

For example, an API user may be able to retrieve agent information:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

while being denied access to administrative resources.

Review which Wazuh user generated the token and determine what that account is actually permitted to access.

Related Guide: How to Configure Wazuh RBAC

Verify RBAC Configuration

If the token authenticates successfully but a particular operation returns 403, inspect the user’s roles and permissions.

Check:

The Wazuh username
Assigned roles
Role mappings
API permissions
Resource permissions
Any restrictions applied to the requested resource

Do not solve a 403 simply by assigning administrator privileges. First identify the missing permission.

This is especially important for automation accounts because excessive privileges increase the impact of a compromised token.

Related Guides:

Check System Time Synchronization

JWT authentication can be sensitive to time-related validation because tokens contain time-based claims.

If the Wazuh server and the system making API requests have significantly incorrect system clocks, authentication behavior can become unpredictable.

Check the server’s time synchronization status:

timedatectl status

On systems using chrony:

chronyc tracking

Look for:

System clock synchronized: yes

and verify that the system’s date and time are correct.

Also check the client machine:

date

If the Wazuh server, reverse proxy, and API client have inconsistent system times, correct NTP/time synchronization before continuing.

Verify TLS Certificates

A token-generation request can fail before authentication if the client cannot establish a trusted TLS connection to the Wazuh API.

Test the endpoint:

curl -v \
  https://<WAZUH_MANAGER_HOSTNAME>:55000/

For diagnostic testing with a self-signed certificate:

curl -k -v \
  https://<WAZUH_MANAGER_HOSTNAME>:55000/

The -k option tells cURL to skip certificate validation.

This can help determine whether the problem is specifically certificate trust, but it should not be the normal production configuration.

Inspect the certificate with:

openssl s_client \
  -connect <WAZUH_MANAGER_HOSTNAME>:55000 \
  -servername <WAZUH_MANAGER_HOSTNAME>

Check for:

Expired certificates
Incorrect hostnames
Missing intermediate certificates
Untrusted certificate authorities
Incorrect certificate/key configuration

Related Guide: How to Fix Wazuh Certificate Errors

Wazuh recommends configuring appropriate certificates for production API deployments rather than relying on the default self-signed certificate.

Check Reverse-Proxy Configuration

If the Wazuh API is behind Nginx, Apache, a load balancer, or another reverse proxy, verify that the proxy is forwarding the Authorization header correctly.

The expected request is:

Authorization: Bearer <JWT_TOKEN>

A proxy configuration that strips or modifies this header can cause a valid token to appear invalid to the Wazuh API.

Test the API directly from a system that can reach the Wazuh server:

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

Then test the same endpoint through the reverse proxy:

curl -k -i \
  "https://<API_PROXY_HOST>/agents" \
  -H "Authorization: Bearer $TOKEN"

If direct access works but proxied access returns 401, investigate the proxy configuration.

Also verify:

HTTPS termination
Header forwarding
Upstream URL
API path rewriting
Host headers
Proxy timeouts
Authentication middleware
Load-balancer behavior

Test Connectivity With cURL

cURL provides a useful baseline because it removes application-specific variables.

First test the API itself:

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/"

Then authenticate:

curl -k -i -X POST \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate"

Finally, test the JWT:

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

This gives you three distinct checkpoints:

API reachable
     ↓
Credentials accepted
     ↓
JWT accepted and authorized

If the first test fails, investigate connectivity or the API service.

Also, if the first succeeds but authentication fails, investigate credentials and authentication configuration.

If authentication succeeds but an endpoint returns 403, investigate RBAC and permissions.

Confirm Wazuh Version Compatibility

Version differences can matter when an application depends on specific API endpoints, parameters, response structures, or configuration options.

Check the Wazuh version:

sudo /var/ossec/bin/wazuh-control info

You can also query manager information through the API:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info" \
  -H "Authorization: Bearer $TOKEN"

When troubleshooting an integration, verify that the API documentation and examples you are following correspond to your installed Wazuh version.

This is particularly important when upgrading Wazuh or maintaining custom API integrations across multiple Wazuh deployments.

Related Guide: How to Upgrade a Wazuh Agent

Wazuh API Token Security Best Practices

A Wazuh API token should be treated as a sensitive authentication credential.

The fact that a JWT may expire does not make exposure harmless; a valid stolen token can still be used during its remaining lifetime with the permissions of its associated user.

Use HTTPS for API Communication

Always use HTTPS when transmitting Wazuh credentials or JWTs.

Use:

https://<WAZUH_MANAGER_IP>:55000

rather than:

http://<WAZUH_MANAGER_IP>:55000

TLS protects credentials and bearer tokens while they are transmitted across the network.

For production environments, configure certificates that clients can properly validate rather than routinely using cURL’s -k option.

Never Expose Tokens in URLs

Do not put a Wazuh API token into a query parameter such as:

https://wazuh.example.com/agents?token=<JWT>

Use the HTTP authorization header instead:

Authorization: Bearer <JWT>

URLs can be recorded by proxies, web servers, browser history, monitoring systems, and other infrastructure.

Keeping bearer credentials in the authorization header reduces unnecessary exposure.

Never Commit Tokens to Git Repositories

Never place live Wazuh tokens in Git repositories.

Avoid:

TOKEN = "eyJhbGciOi..."

in source-controlled files.

Even private repositories should not be treated as appropriate long-term secret stores.

If a token is accidentally committed:

Treat it as compromised.
Remove it from the active application.
Generate a replacement.
Remove the secret from the repository history where appropriate.
Review access logs for suspicious API activity.
Investigate how the secret was exposed.

Store Tokens in Environment Variables or Secret Managers

For simple scripts, environment variables can keep secrets separate from source code:

export WAZUH_API_TOKEN="<JWT_TOKEN>"

Then:

import os

token = os.environ["WAZUH_API_TOKEN"]

For production applications, use a dedicated secret-management platform where practical.

The objective is to prevent API tokens from becoming embedded in application source, configuration repositories, container images, or deployment artifacts.

Apply Least-Privilege Permissions

Use a dedicated Wazuh API identity for each significant integration where practical.

For example:

Monitoring application
    ↓
Monitoring API user
    ↓
Read-only role

Automation application
    ↓
Automation API user
    ↓
Specific operational permissions

Administrator
    ↓
Administrative API user
    ↓
Broad administrative permissions

This makes compromise of one integration less damaging to the overall Wazuh environment.

Rotate Credentials Regularly

Regular credential rotation reduces the amount of time an exposed credential can remain useful.

Review:

API usernames
API passwords
Secret-manager entries
Automation credentials
Long-running application configurations

Because Wazuh JWTs have a configured expiration period, applications should also be designed to obtain fresh tokens rather than assuming one token will work indefinitely.

Revoke Compromised Credentials

If a Wazuh API token is exposed, treat it as compromised immediately.

Do not assume that an attacker will be unable to use it.

Depending on your deployment and authentication design, invalidate the affected credential by taking appropriate account or authentication-configuration action, then issue replacement credentials.

Also investigate whether the token was used unexpectedly.

A compromised administrator token should receive particularly urgent attention because its authorization context may allow extensive Wazuh configuration changes.

Restrict API Network Access

Do not expose the Wazuh API unnecessarily to the public Internet.

Use network controls such as:

Firewalls
Security groups
VLAN segmentation
VPN access
Private networks
Reverse proxies
Network ACLs

For example:

Automation Network
       |
       | HTTPS :55000
       v
Firewall
       |
       v
Wazuh API

Only trusted systems that require API access should be able to reach the API whenever practical.

Monitor API Authentication Activity

Monitor authentication and API activity for unexpected behavior.

Look for:

Repeated authentication failures
Requests from unexpected hosts
Unusual administrative API calls
Sudden changes in request volume
Access outside normal operating hours
Repeated attempts against restricted resources

Centralized logging can help correlate API activity with other security events.

Related Guide: How to Configure Wazuh Audit Logs

Avoid Sharing Tokens Between Applications

Do not use one administrator token across multiple scripts and services simply for convenience.

Instead:

Application A → Token/User A
Application B → Token/User B
Application C → Token/User C

This provides better isolation and accountability.

If Application B is compromised, its credentials can be disabled without necessarily disrupting Application A or Application C.

Remove Unused Credentials

Regularly review Wazuh API users and credentials.

Remove or disable accounts associated with:

Retired applications
Decommissioned servers
Old automation
Former integrations
Temporary testing
Obsolete development environments

Unused credentials increase the attack surface without providing operational value.

Wazuh API Token vs API Username and Password

The terms “API token” and “API username and password” can be confusing because Wazuh uses the username and password during the authentication process that generates the JWT.

The important distinction is that the username/password pair is used to obtain the token, while the JWT is then used to authenticate subsequent API requests.

Authentication Differences

With username/password authentication, the client initially sends credentials to:

POST /security/user/authenticate

Wazuh validates those credentials and returns a JWT.

The subsequent API request uses:

Authorization: Bearer <JWT>

The workflow therefore looks like:

Username + Password
        ↓
Authentication endpoint
        ↓
Wazuh API token
        ↓
Bearer authentication
        ↓
Protected API endpoint

The username and password are therefore not an alternative mechanism for repeatedly calling protected endpoints in the normal JWT workflow.

They are the credentials used to authenticate and obtain the token.

Security Differences

Sending long-term credentials repeatedly creates more opportunities for accidental exposure.

A JWT provides a separate, time-limited credential that can be used for subsequent requests.

However, the token itself must still be protected.

For example:

Long-term password
       ↓
Used to obtain JWT
       ↓
Shorter-lived bearer credential
       ↓
Used for API operations

A stolen JWT may still be usable until it expires, so token-based authentication should not be interpreted as “safe even if exposed.”

The security advantage comes from properly managing the credential lifecycle, token expiration, TLS, RBAC, and secret storage.

Automation Considerations

API tokens are generally convenient for automation because applications can authenticate and then reuse the resulting JWT for the required API calls.

For example:

TOKEN=$(curl -s -k \
  -u "$WAZUH_USER:$WAZUH_PASSWORD" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true")

Then:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

A production implementation should obtain the initial credentials from a secure secret store rather than embedding them directly in the script.

For long-running applications, implement logic that obtains a new token when the current token expires.

Token Management

A token introduces another credential that needs lifecycle management.

Good token management includes:

Secure generation
Secure storage
Controlled distribution
Expiration
Renewal
Monitoring
Replacement after compromise
Removal when no longer required

The associated Wazuh user and its RBAC permissions must also be managed.

This means token management should be part of the broader Wazuh access-control process rather than treated as an isolated API configuration task.

Related Guide: How to Backup Wazuh RBAC Configurations

When to Use Each Authentication Method

For normal Wazuh API workflows, use the username/password credentials to authenticate against the authentication endpoint and obtain a JWT, then use the JWT as the bearer credential for subsequent protected requests.

A practical model is:

Scenario	Recommended approach
Initial API authentication	Wazuh username/password
Subsequent API requests	JWT bearer token
Short-lived scripts	Obtain token at runtime
Long-running applications	Obtain and renew tokens as needed
CI/CD automation	Secret-managed credentials + runtime JWT
Monitoring integration	Dedicated low-privilege API user + JWT
Administrative automation	Dedicated privileged account + JWT, with strict secret controls
Testing	cURL/Postman with a temporary or appropriately scoped credential

The key takeaway is that Wazuh API tokens and username/password credentials are complementary parts of the authentication workflow rather than completely separate authentication systems.

The credentials establish the user’s identity, while the JWT provides the bearer credential used to access protected API endpoints.

For production environments, combine this authentication model with RBAC, HTTPS, least privilege, restricted network access, secure secret storage, token expiration, and authentication monitoring.

Real-World Wazuh API Token Example

Consider an enterprise security operations center (SOC) managing several hundred Windows and Linux endpoints through a centralized Wazuh deployment.

The SOC uses Wazuh for endpoint monitoring, security analytics, file-integrity monitoring, vulnerability detection, and incident investigation.

Its security automation platform needs to periodically retrieve agent and security information from the Wazuh API.

Rather than giving the automation platform a general-purpose administrator account, the SOC creates a dedicated API identity with only the permissions required by the integration.

This architecture provides better credential isolation, easier auditing, and a smaller blast radius if the automation system is compromised.

Describe an Enterprise SOC Deployment

A simplified architecture might look like this:

                         Enterprise Endpoints
                       /         |          \
                      /          |           \
               Windows       Linux        Servers
                   \             |            /
                    \            |           /
                     v           v          v
                       Wazuh Agents
                              |
                              v
                        Wazuh Manager
                              |
                              |
                       Wazuh Server API
                              |
                              v
                    Security Automation

The automation platform needs to query Wazuh but does not need unrestricted administrative access.

For example, it may need to retrieve:

Agent inventory
Agent status
Operating-system information
Security-related data
Manager health information

It does not need to modify RBAC configuration, create users, or change core Wazuh security settings.

Create a Dedicated API User

The first step is to create a dedicated Wazuh API identity for the automation system.

Avoid using a personal administrator account for unattended automation.

A dedicated account provides:

Clear attribution
Easier credential rotation
Better auditing
Reduced privilege
Easier incident response
Separation between human and machine access

A suitable naming convention might be:

wazuh-automation

or:

wazuh-monitoring-api

The exact username is not important. What matters is that the account has a clearly defined purpose.

Assign Appropriate RBAC Permissions

Next, assign the account a role that provides only the access required by the automation.

For example:

wazuh-monitoring-api
        |
        v
Monitoring role
        |
        +-- Read agent information
        +-- Read manager information
        +-- Read required security data
        |
        X-- No user administration
        X-- No RBAC administration
        X-- No unnecessary configuration changes

If the integration only requires read access, do not grant write or administrative permissions.

This follows the principle of least privilege and limits the potential impact of credential compromise.

Generate Authentication Credentials

Once the user and permissions are configured, obtain the credentials required to authenticate against the Wazuh API.

The API authentication endpoint is:

POST /security/user/authenticate

For example:

curl -s -k \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  -X POST \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

For production automation, retrieve the username and password from a secrets-management system rather than placing them directly in the script.

Configure an Automation Script

The automation platform can obtain a JWT when the workflow starts.

A simple Bash example is:

#!/bin/bash

set -euo pipefail

WAZUH_API="https://<WAZUH_MANAGER_IP>:55000"

TOKEN=$(curl -s -k \
  -u "$WAZUH_USER:$WAZUH_PASSWORD" \
  -X POST \
  "$WAZUH_API/security/user/authenticate?raw=true")

if [ -z "$TOKEN" ]; then
    echo "Failed to obtain Wazuh API token."
    exit 1
fi

echo "Wazuh API authentication successful."

The important security property is that the script does not print the token itself.

The credentials can be injected through the automation platform:

export WAZUH_USER="<API_USER>"
export WAZUH_PASSWORD="<API_PASSWORD>"

For an enterprise deployment, these values should preferably originate from a secrets manager or protected CI/CD credential store.

Authenticate Against the Wazuh API

After obtaining the JWT, the script supplies it as a Bearer token:

curl -s -k \
  "$WAZUH_API/manager/info" \
  -H "Authorization: Bearer $TOKEN"

The automation system can then reuse the token for other API calls during its valid lifetime.

A successful request should return JSON data rather than an authentication error.

Retrieve Security Data

Suppose the automation platform needs to retrieve Wazuh agent information.

It could query:

curl -s -k \
  "$WAZUH_API/agents?pretty=true" \
  -H "Authorization: Bearer $TOKEN"

The returned information can then be processed by the automation platform.

For example:

Wazuh API
    |
    v
Agent data
    |
    v
Automation platform
    |
    +--> Monitoring dashboard
    +--> Ticketing system
    +--> SOC workflow
    +--> Security report

The automation platform should only request the API resources it actually needs.

Monitor and Secure the Credentials

The final component is credential management.

The SOC should monitor:

Authentication failures
API access patterns
Unexpected source addresses
Excessive API requests
Unauthorized endpoint attempts
Changes to the API user’s roles
Credential rotation events

The API credentials should be stored securely and never committed to source control.

If the automation platform is compromised, the SOC can disable or rotate the dedicated API credentials without necessarily affecting human administrator accounts or unrelated integrations.

This compartmentalized approach is significantly safer than using one administrator credential throughout the environment.

Related Guide: How to Configure Wazuh Audit Logs

Frequently Asked Questions

Question: What Is a Wazuh API Token?

A Wazuh API token is a JSON Web Token (JWT) issued by the Wazuh server API after successful authentication.

The JWT is supplied as a Bearer token in the Authorization header when accessing protected API endpoints.

Question: How Do I Get a Wazuh API Token?

Authenticate against the Wazuh API’s /security/user/authenticate endpoint using valid Wazuh API credentials.

For example:

curl -k -X POST \
  -u "<WAZUH_API_USER>:<WAZUH_API_PASSWORD>" \
  "https://<WAZUH_MANAGER_IP>:55000/security/user/authenticate?raw=true"

Wazuh returns a JWT that can then be used for subsequent API requests.

Question: How Do I Authenticate to the Wazuh API?

First authenticate with a valid Wazuh API username and password to obtain a JWT.

Then include that JWT in subsequent requests:

Authorization: Bearer <JWT_TOKEN>

Wazuh documents JWT authentication as the mechanism used for protected API endpoints.

Question: How Do I Use a Wazuh API Token With cURL?

Store the token in a variable:

TOKEN="<JWT_TOKEN>"

Then send it with the Bearer authorization header:

curl -k \
  "https://<WAZUH_MANAGER_IP>:55000/agents" \
  -H "Authorization: Bearer $TOKEN"

Question: How Do I Use a Wazuh API Token in Python?

Use an HTTP library such as requests and provide the token through the authorization header:

import os
import requests

token = os.environ["WAZUH_API_TOKEN"]

headers = {
    "Authorization": f"Bearer {token}"
}

response = requests.get(
    "https://<WAZUH_MANAGER_IP>:55000/agents",
    headers=headers,
    timeout=30
)

response.raise_for_status()

data = response.json()

Avoid hard-coding the token directly into the Python source code.

Question: How Long Does a Wazuh API Token Last?

The token lifetime is controlled by Wazuh’s authentication-token expiration configuration.

Wazuh exposes the auth_token_exp_timeout setting, which controls the expiration period in seconds.

The exact lifetime therefore depends on your Wazuh API configuration rather than being universally fixed.

Check the configured value through the API security configuration or your Wazuh API configuration.

Question: Can I Revoke a Wazuh API Token?

A JWT is designed to remain valid until it expires unless the surrounding authentication state or configuration causes it to become invalid.

If you suspect that a token has been compromised, do not continue using it.

Take appropriate action against the associated Wazuh account or credentials, generate replacement credentials, and investigate whether the token was used unexpectedly.

For long-lived integrations, designing the application around token expiration and credential rotation is preferable to treating a JWT as a permanent credential.

Question: Can Wazuh API Tokens Have Different Permissions?

Yes, but the permissions are determined by the Wazuh user and its authorization context rather than by arbitrarily changing the JWT itself.

For example:

Administrator user
    ↓
Administrator token
    ↓
Broad permissions

Analyst user
    ↓
Analyst token
    ↓
Restricted permissions

Use dedicated users and appropriate RBAC roles when different applications require different levels of API access.

Question: Why Does My Wazuh API Token Return 401 Unauthorized?

A 401 Unauthorized response generally indicates an authentication problem.

Common causes include:

Expired token
Invalid token
Missing authorization header
Incorrect Bearer syntax
Incorrect credentials during token generation
Authentication configuration problems

Generate a fresh token and test it against a simple endpoint:

curl -k -i \
  "https://<WAZUH_MANAGER_IP>:55000/manager/info" \
  -H "Authorization: Bearer $TOKEN"

If the problem persists, inspect the API logs and verify the authentication endpoint.

Question: Why Does My Wazuh API Token Return 403 Forbidden?

A 403 Forbidden generally means that authentication succeeded but the associated user does not have permission to perform the requested operation.

Check:

Wazuh user roles
RBAC permissions
Requested API endpoint
Required operation privileges

Generating another token for the same user will generally not solve a permissions problem because the new token still represents the same authorization context.

Question: Why Is My Wazuh API Token Not Working?

Start with the following checks:

Verify that the Wazuh API is running.
Confirm the API hostname and port.
Generate a fresh token.
Confirm the Authorization: Bearer format.
Check token expiration.
Verify user permissions.
Review RBAC configuration.
Check system time synchronization.
Verify TLS certificates.
Inspect the Wazuh API logs.

Testing the request with cURL is useful because it removes application-specific variables.

Question: Are Wazuh API Tokens More Secure Than Passwords?

API tokens can improve credential handling because the initial username/password authentication is separated from subsequent API requests, and tokens can have a defined expiration period.

However, a JWT is still a bearer credential.

Anyone who obtains a valid token may be able to use it according to the permissions of its associated account until it becomes invalid.

Therefore, token-based authentication should be combined with:

HTTPS
Secure secret storage
Least privilege
Token expiration
Credential rotation
Network restrictions
API monitoring

Question: Where Should I Store a Wazuh API Token?

For short-lived scripts, an environment variable can be appropriate.

For production applications, use a dedicated secrets-management mechanism where available.

Avoid storing tokens in:

Git repositories
Public configuration files
Source code
Container images
Application logs
URLs
Screenshots

If a token is accidentally exposed, treat it as compromised and replace the associated credentials.

Question: Can I Use Wazuh API Tokens for Automation?

Yes. API tokens are particularly useful for automation because scripts and applications can authenticate, obtain a JWT, and then use the token for authorized API operations.

Common applications include:

Bash scripts
Python applications
PowerShell
Ansible workflows
Monitoring platforms
CI/CD pipelines
SOAR integrations
Custom security applications

Use a dedicated API user with only the permissions required by the automation.

Question: How Do I Rotate Wazuh API Credentials?

A practical rotation process is:

Create or prepare replacement credentials.
Assign the replacement identity the required RBAC permissions.
Update the application or secret manager.
Authenticate with the replacement credentials.
Test the integration.
Disable or remove the old credentials.
Monitor for authentication failures.
Document the rotation.

For critical integrations, perform the transition in a controlled window so that credential rotation does not unnecessarily interrupt security automation.

Question: How Do I Troubleshoot Wazuh API Authentication?

Use a layered troubleshooting process:

1. Check network connectivity
       ↓
2. Check Wazuh manager/API service
       ↓
3. Verify HTTPS/TLS
       ↓
4. Test authentication endpoint
       ↓
5. Generate a fresh JWT
       ↓
6. Verify Bearer header
       ↓
7. Test a permitted endpoint
       ↓
8. Check RBAC for 403 errors
       ↓
9. Review API logs
       ↓
10. Check version compatibility

This approach helps distinguish connectivity problems from authentication, authorization, and application-level problems.

Conclusion

Wazuh API token authentication provides a practical mechanism for securely interacting with the Wazuh server API from scripts, applications, automation platforms, and other security tools.

The basic workflow is straightforward:

Wazuh credentials
      ↓
/security/user/authenticate
      ↓
JWT generated
      ↓
Authorization: Bearer <TOKEN>
      ↓
Protected Wazuh API endpoint
      ↓
Authentication + RBAC authorization
      ↓
API response

The most important security consideration is that obtaining a token is only one part of secure API access.

The Wazuh user behind the token should have only the permissions required for its intended purpose.

Store tokens securely, use HTTPS, avoid exposing credentials in URLs or source code, restrict API network access, monitor authentication activity, and rotate compromised or obsolete credentials.

For automation, the recommended workflow is to retrieve credentials from a protected secret store, authenticate at runtime, use the resulting JWT only for the required operations, handle token expiration, and avoid logging the token.

Finally, test both sides of the authorization model.

A properly configured API identity should be able to access the endpoints it needs while receiving appropriate authorization failures when attempting restricted operations.

By combining JWT authentication with Wazuh RBAC, least-privilege design, secure secret management, TLS, network controls, and continuous monitoring, you can build Wazuh API integrations that are both operationally useful and appropriately protected.