Skip to content
API
Configuration
Authentication

Authentication

Overview

Watchtower’s HTTP API uses token-based authentication to protect sensitive endpoints.

Two separate tokens are available:

Authentication is enforced at the route level after other middleware (rate limiting, CORS, etc.).

HTTP API Token

Use the HTTP API Token configuration option to set the primary authentication token.

This token is required when any of the following endpoints are enabled:

Clients must include the token using the Authorization: Bearer <token> header:

curl -H "Authorization: Bearer your-secure-token" http://localhost:8080/v1/metrics

Invalid or missing tokens result in 401 Unauthorized. Failed authentication attempts are logged with the client IP address.

A cookie-based fallback is also supported for clients that cannot set custom headers. The token may be provided in a cookie named access_token:

Cookie: access_token=your-secure-token
The cookie fallback exists primarily for browser-based or limited clients. The header Authorization: Bearer is the recommended method.

Cookie auth and CSRF

When the http-api-cors-origins is configured and credentials are allowed (for example, Access-Control-Allow-Credentials: true), the cookie fallback is vulnerable to cross-site request forgery (CSRF). A browser on an attacker-controlled origin can issue authenticated POST requests to the API without the user’s knowledge. Prefer header-based Authorization: Bearer auth.

HTTP API Events Token

The /v1/events endpoint uses a separate token set via the HTTP API Events Token configuration option.

This token is required when the /v1/events endpoint is enabled.

The events token can be supplied in two ways:

  • Authorization: Bearer header (recommended for most clients)
  • access_token query parameter (required for browser EventSource, which cannot set custom headers)

Example using the header:

curl -N -H "Authorization: Bearer your-events-token" http://localhost:8080/v1/events

Example using the query parameter:

curl -N "http://localhost:8080/v1/events?access_token=your-events-token"

In JavaScript (for browsers):

const eventSource = new EventSource('http://localhost:8080/v1/events?access_token=your-events-token');
The events token is intentionally separate from the main API token. Query parameters can appear in access logs, browser history, and proxy logs. Using a dedicated token limits exposure.

See the Events endpoint documentation for more details.

Examples

Tokens can be provided to Watchtower using Docker Secrets, environment variables, or CLI flags.

Use Compose secrets to mount the token file inside the container and point the environment variable at the mounted path (commonly /run/secrets/<name>).

services:
    watchtower:
        image: nickfedor/watchtower:latest
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
        secrets:
            - http_api_token
        environment:
            - WATCHTOWER_HTTP_API_TOKEN=/run/secrets/http_api_token
            # Enable an endpoint that requires authentication
            - WATCHTOWER_HTTP_API_ENDPOINTS=metrics
        ports:
            - "8080:8080"
        restart: unless-stopped

secrets:
    http_api_token:
        file: ./secrets/http_api_token.txt

Unauthenticated Endpoints

The following endpoints do not require authentication when enabled:

  • Health probes: /livez, /readyz, /startupz
  • Swagger UI: /swagger/* (“Try it out” functionality still requires authorization)

Best Practices

  • Generate strong, random tokens (for example: openssl rand -base64 32).
  • Use a separate events token when enabling the /v1/events endpoint.
  • Always run the HTTP API behind TLS in production (see the TLS documentation).
  • Never expose the HTTP API directly to the public internet.
  • Store tokens using Docker Secrets or a secrets manager rather than plain environment variables or CLI flags when possible.
  • Rotate tokens if they may have been exposed.
  • Combine authentication with network controls (firewalls, reverse proxies with IP allowlists).

Related Documentation

Last updated on
Host and PortTLS