Getting Started

Download PDF

Generate LogZilla API tokens, authenticate HTTP requests, and verify access with curl against the interactive docs at /api/docs and /incoming/docs

Getting Started

The LogZilla API provides secure, programmatic access to log management and analysis capabilities through standard HTTP/HTTPS requests. Authentication token management, basic API usage patterns, and verification procedures enable integration with LogZilla's RESTful interface.

LogZilla API

Note: Interactive documentation endpoints

  • Main API (management, queries): /api/docs
  • HTTP Receiver (data ingestion): /incoming/docs

Prerequisites

  • Administrative or root access to LogZilla server
  • Command-line access for token management
  • HTTP client (curl, wget, or application capable of HTTP requests)
  • Understanding of REST API concepts

Authentication

All API functions and HTTP event receipt require authentication via an authorization token. An auth token is a long alphanumeric sequence that serves as a key associated with a specific user. When provided to LogZilla, the system verifies that the token has been configured to allow API or back-end access. Auth tokens must be kept private as they authorize access to LogZilla data. Tokens persist indefinitely until explicitly revoked. The token value is shown once, when the token is created; the list and info commands show a masked form and the token id, and revocation takes the id.

Two types of auth tokens exist:

  • User tokens - Full-function tokens with complete API access
  • Ingest-only tokens - Limited to HTTP Event Receiver data ingestion

Token scope and usage

  • User tokens are valid for all management API endpoints under /api/* and for ingestion under /incoming/*.
  • Ingest-only tokens are valid only for the HTTP Receiver under /incoming/* and are rejected by the main management API under /api/*.
  • The HTTP Receiver accepts tokens via Authorization: token ..., the X-LZ-Access-Key header, or the AUTHTOKEN query parameter.

Administrator or root access is required for token management. This can be accomplished through privileged login or sudo.

Administrators can manage tokens using the logzilla authtoken CLI tool:

bash
# logzilla authtoken -h
usage: authtoken [-h] [-d] [-q] {create,revoke,info,list} ...

LogZilla AuthToken manipulation

positional arguments:
  {create,revoke,info,list}
    create              create new token
    revoke              revoke token
    info                show token info
    list                list active tokens

options:
  -h, --help            show this help message and exit
  -d, --debug           debug mode
  -q, --quiet           notify only on warnings and errors (be quiet).

Auth Token Management

Auth Token Generation

Administrators can create new full-function user auth tokens using logzilla authtoken create:

bash
root[~]: # logzilla authtoken create
Creating USER token
Id: 12
user-0123456789abcdef0123456789abcdef0123456789abcdef

The output displays the generated auth token on the last line, and the value is not shown again.

Tokens can be created for specific users by specifying the username:

bash
root[~]: # logzilla authtoken create -U john
Creating USER token
Id: 13
user-0123456789abcdef0123456789abcdef0123456789abcdef

Ingest-only tokens are created using the --ingest-only option:

bash
root[~]: # logzilla authtoken create --ingest-only
Creating INGEST token
Id: 14
ingest-0123456789abcdef0123456789abcdef0123456789abcdef

Auth Token Review

Active auth tokens can be listed using logzilla authtoken list; the list shows each token's id and a masked form (type prefix and last four characters), never the value:

bash
# logzilla authtoken list
====  ============  ======  ==========  ===========================
  Id  Token         Type    Username    Created
====  ============  ======  ==========  ===========================
  12  user-...cdef  USER    admin       2022-05-12T14:37:51.769886Z
====  ============  ======  ==========  ===========================

Detailed information for a specific auth token can be retrieved using logzilla authtoken info with the token id from the list:

bash
# logzilla authtoken info 12
Id: 12
Token: user-...cdef
Type: USER
User: admin
Created: 2022-05-12T14:37:51.769886Z

Auth Token Revocation

Auth tokens can be revoked to permanently delete them and prevent further LogZilla access. Revocation is performed using logzilla authtoken revoke and takes the token id from the list:

bash
# logzilla authtoken revoke 12
Token 12 revoked.

Using the Auth Token

Authorization tokens can be provided to the API in two ways:

  • Authorization header
  • AUTHTOKEN parameter in the request URI

In the examples below, replace YOUR_TOKEN with a token created as shown above. The token values printed by logzilla authtoken create on this page are samples, not working tokens.

Header-Based Authentication

Tokens can be included in the Authorization HTTP header:

http
Authorization: token YOUR_TOKEN

URI-Based Authentication

Tokens can be included as a parameter in the request URL:

http
POST /incoming?AUTHTOKEN=YOUR_TOKEN

Example

Once a token is created, users can connect to the API using standard HTTP methods (POST, GET, PATCH, PUT, etc.).

The following example demonstrates sending a sample event to LogZilla using the standard events array JSON structure and header-based authentication:

bash
curl \
  -H 'Content-Type: application/json' \
  -H 'Authorization: token YOUR_TOKEN' \
  -X POST -d '{"events":[{"host":"web01","program":"sample","message":"Test Message"}]}' \
  'http://logzilla.mycompany.com/incoming'

Verification

To verify API access is working correctly:

  1. Create an auth token using the steps above

  2. Test API connectivity with a simple request:

    bash
    curl -H "Authorization: token YOUR_TOKEN" \
    "http://your-logzilla-server/api/auth/"

  3. Successful authentication returns a JSON response with user information

References

Getting Started | LogZilla Documentation