# How to Set Up and Configure wigolo's REST API Server with Token Authentication

> Learn to set up and configure wigolo's REST API server with token authentication. Secure your API endpoints using token authorization for enhanced security.

- Repository: [Towhid Khan/wigolo](https://github.com/KnockOutEZ/wigolo)
- Tags: how-to-guide
- Published: 2026-07-29

---

**Set the `WIGOLO_API_TOKEN` environment variable when running `wigolo serve` on any non-loopback interface to require `Authorization: Bearer <token>` headers on all `/v1/*`, [`/openapi.json`](https://github.com/KnockOutEZ/wigolo/blob/main//openapi.json), `/mcp`, and `/sse` endpoints while keeping the `/health` endpoint publicly accessible for load balancer probes.**

The KnockOutEZ/wigolo repository exposes a plain-JSON REST surface via the `wigolo serve` command. While the daemon binds to `127.0.0.1:3333` without authentication by default, any non-loopback configuration triggers a fail-closed security policy that mandates bearer token authentication according to [`docs/rest-api.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/rest-api.md) and [`docs/configuration.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/configuration.md).

## Understanding the Fail-Closed Security Model

When binding to `0.0.0.0` or any public IP address, wigolo aborts startup unless it detects a valid authentication token. This prevents accidental exposure of intelligence endpoints to untrusted networks. Internally, the token is read once at startup and stored in a process-private variable; subsequent requests validate the `Authorization` header using a case-insensitive comparison against the stored bearer scheme.

## Configuring Token Sources

### Environment Variable Method

Set `WIGOLO_API_TOKEN` before launching the daemon. This approach is suitable for development environments or secret managers that inject variables directly into the process environment.

```bash
export WIGOLO_API_TOKEN=$(openssl rand -hex 32)
wigolo serve --host 0.0.0.0 --port 3333

```

### File-Based Secret for Containerized Deployments

For Docker or Kubernetes deployments, mount the token as a file and reference it via `WIGOLO_API_TOKEN_FILE`. This pattern prevents the token from appearing in process listings, following the security hardening guidance in [`docs/privacy-security.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/privacy-security.md).

```bash

# Create secret file on the host

echo "$WIGOLO_API_TOKEN" > /run/secrets/wigolo-token

docker run -p 3333:3333 \
  -e WIGOLO_API_TOKEN_FILE=/run/secrets/wigolo-token \
  -v /run/secrets/wigolo-token:/run/secrets/wigolo-token:ro \
  ghcr.io/knockoutez/wigolo serve --host 0.0.0.0

```

## Starting the Server on Public Interfaces

When the daemon detects a non-loopback bind and cannot locate a token via `WIGOLO_API_TOKEN` or `WIGOLO_API_TOKEN_FILE`, it aborts with a clear error message before opening network sockets. Protected endpoints include:

- `/v1/tools`
- `/v1/search`  
- [`/openapi.json`](https://github.com/KnockOutEZ/wigolo/blob/main//openapi.json)
- `/mcp`
- `/sse`

The `/health` endpoint remains accessible without authentication for monitoring and load balancer health probes.

## Making Authenticated Requests

All protected endpoints require the `Authorization` header with the bearer token configured at startup. Concrete examples are also available in [`examples/rest-curl/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/examples/rest-curl/README.md).

### Listing Available Tools

```bash
curl -s -H "Authorization: Bearer $WIGOLO_API_TOKEN" \
     http://<host>:3333/v1/tools

```

### Performing Searches

```bash
curl -s -X POST http://<host>:3333/v1/search \
     -H "Authorization: Bearer $WIGOLO_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"query":"local-first web intelligence","max_results":5}'

```

### Health Checks

Load balancers can probe the service without providing a token:

```bash
curl -s http://<host>:3333/health

```

## Disabling Authentication (Development Only)

Override the fail-closed policy using the `--allow-unauthenticated` flag or by setting `WIGOLO_SERVE_ALLOW_UNAUTHENTICATED=1`. This bypass is explicitly documented in [`docs/self-hosting.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/self-hosting.md) for local development only and should never be used in production deployments.

## SDK Configuration

Both official SDKs mirror the REST API authentication model:

- **TypeScript SDK**: Reads the `WIGOLO_API_TOKEN` environment variable by default, as documented in [`sdks/typescript/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/sdks/typescript/README.md)
- **Python SDK**: Accepts a `token` parameter that maps to the bearer header, detailed in [`sdks/python/README.md`](https://github.com/KnockOutEZ/wigolo/blob/main/sdks/python/README.md)

## Summary

- **Fail-Closed Default**: Non-loopback binds (`0.0.0.0` or public IPs) require `WIGOLO_API_TOKEN` or `WIGOLO_API_TOKEN_FILE`
- **Header Format**: Protected endpoints require `Authorization: Bearer <token>` with case-insensitive scheme matching
- **Health Endpoint**: The `/health` route remains publicly accessible for infrastructure monitoring
- **Container Security**: Prefer `WIGOLO_API_TOKEN_FILE` mounted as a Docker secret over environment variables
- **Development Override**: Use `--allow-unauthenticated` or `WIGOLO_SERVE_ALLOW_UNAUTHENTICATED=1` strictly for local testing

## Frequently Asked Questions

### What happens if I start wigolo on 0.0.0.0 without setting a token?

The server aborts during initialization with a clear error message stating that authentication is required for non-loopback interfaces. This prevents accidental exposure of sensitive endpoints before the process opens network sockets.

### Which endpoints require the bearer token?

All routes under `/v1/*`, plus [`/openapi.json`](https://github.com/KnockOutEZ/wigolo/blob/main//openapi.json), `/mcp`, and `/sse`, require the `Authorization: Bearer <token>` header. The only exception is `/health`, which remains open for load balancer probes and monitoring systems.

### How do I rotate the authentication token?

Restart the wigolo process with the new token value. Since the token is loaded once at startup into a process-private variable, token rotation requires a process restart. For zero-downtime deployments, drain connections via a load balancer before switching instances.

### Can I use Docker secrets instead of environment variables?

Yes. Write the token to a file (e.g., `/run/secrets/wigolo-token`), mount it into the container, and set `WIGOLO_API_TOKEN_FILE` to that path. This method keeps credentials out of the process environment and is recommended in [`docs/privacy-security.md`](https://github.com/KnockOutEZ/wigolo/blob/main/docs/privacy-security.md) for production containerized deployments.