# How REST API Authentication and Authorization Work in AgentsView

> Learn how AgentsView's REST API handles authentication and authorization with bearer tokens and middleware for secure access and configurable bypasses.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: api-reference
- Published: 2026-07-04

---

**AgentsView protects its REST endpoints using a lightweight bearer-token middleware that validates shared secrets against configuration, granting binary access to protected routes while allowing CORS pre-flight and remote-sync requests to bypass checks when configured.**

AgentsView implements a straightforward security model for its HTTP server using a shared secret authentication scheme. The logic is centralized in [`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go), where the `authMiddleware` function intercepts requests to validate credentials before they reach business logic handlers. This design provides a binary authorization model where possession of the configured token grants full API access, managed dynamically through the settings endpoints.

## Protected Routes and Path Matching

The server distinguishes between public static assets and protected API endpoints using the `protectedPath` helper. Only requests targeting paths beginning with `/api/` (plus profiling endpoints when enabled) trigger authentication checks.

In [`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go), the middleware applies this filter:

```go
// Protected paths start with /api/
if !s.protectedPath(r.URL.Path) {
    next.ServeHTTP(w, r)
    return
}

```

All other assets are served without authentication gates.

## Configuration and Middleware Setup

Authentication behavior is controlled by two configuration values defined in the server configuration: `cfg.AuthToken` (the shared secret) and `cfg.RequireAuth` (a boolean flag). These values are loaded at startup from CLI flags, environment variables, or config files in [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go).

The `authMiddleware` acquires a read-lock on the configuration to safely check these values:

```go
s.cfgMu.RLock()
token := s.cfg.AuthToken
requireAuth := s.cfg.RequireAuth
s.cfgMu.RUnlock()

```

When `requireAuth` is false, the middleware skips token validation for most routes (except remote-sync paths, which still require identification).

## Token Validation: Headers and Query Parameters

For standard HTTP requests, the middleware extracts the token from the `Authorization: Bearer <token>` header. However, for Server-Sent Events (SSE) endpoints such as `/watch` and `/api/v1/events`, the middleware also accepts a `?token=` query parameter because browsers cannot set custom headers on `EventSource` connections.

The extraction logic in [`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go) (lines 29-44) handles both mechanisms:

```go
// Check Authorization header first
authHeader := r.Header.Get("Authorization")
if strings.HasPrefix(authHeader, "Bearer ") {
    providedToken = strings.TrimPrefix(authHeader, "Bearer ")
}

// Fallback to query parameter for SSE endpoints
if providedToken == "" {
    providedToken = r.URL.Query().Get("token")
}

```

## Special Handling for CORS and Remote Sync

The middleware includes specific logic for cross-origin resource sharing (CORS) scenarios. `OPTIONS` pre-flight requests are allowed to pass through immediately. When authentication is required and a token is configured, these requests are marked as authenticated so that subsequent CORS middleware permits the pre-flight to complete.

Remote-sync endpoints (`/api/v1/remote-sync/`) receive special treatment via the `isRemoteSyncPath` helper. Even when `requireAuth` is disabled globally, these routes require token validation to establish the "remote" authentication context, allowing machine-to-machine synchronization without exposing the entire API to unauthenticated calls.

## Authorization Model and Context Propagation

AgentsView employs a binary authorization scheme rather than role-based access control. When `requireAuth` is true, any request lacking the valid bearer token receives a `401 Unauthorized` response. The `setCORSOnAuthError` helper ensures appropriate `Access-Control-Allow-Origin` headers are set so browsers can read the error.

Upon successful validation, the middleware injects authentication status into the request context using `ctxKeyRemoteAuth = true`. Downstream middleware, including host-check and CORS handlers, consult `isRemoteAuth` to relax restrictions for trusted remote calls.

## Managing Authentication via Settings

The current token and `requireAuth` flag can be inspected and modified at runtime through the `/api/v1/settings` endpoints defined in [`internal/server/settings.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/settings.go). The JSON structures (lines 3-28) expose these values via GET and PUT handlers, allowing dynamic reconfiguration without server restarts. The token is redacted in UI responses unless the client is a local request.

Example payload structure:

```go
type Settings struct {
    AuthToken   string `json:"auth_token"`
    RequireAuth bool   `json:"require_auth"`
}

```

## Summary

- AgentsView uses a **shared secret bearer token** scheme implemented in [`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go) to protect REST API endpoints.
- The `authMiddleware` validates tokens from `Authorization: Bearer` headers or `?token=` query parameters for SSE endpoints (`/watch`, `/api/v1/events`).
- Authentication is **binary**: possession of the configured `AuthToken` grants full API access when `RequireAuth` is enabled.
- **Remote-sync routes** (`/api/v1/remote-sync/`) always require token validation to establish remote authentication context, even when global auth is disabled.
- The system supports **dynamic configuration** via the `/api/v1/settings` endpoints, allowing runtime changes to authentication parameters.

## Frequently Asked Questions

### How do I authenticate requests to AgentsView API endpoints?

Include the bearer token in the `Authorization` header using the format `Authorization: Bearer <your-token>`. For browser-based Server-Sent Event connections to `/watch` or `/api/v1/events`, append the token as a query parameter (`?token=<your-token>`) because EventSource connections cannot set custom headers.

### What happens if the authentication token is missing or invalid?

The server returns a `401 Unauthorized` status code. According to [`internal/server/auth.go`](https://github.com/kenn-io/agentsview/blob/main/internal/server/auth.go) (lines 141-149), the `setCORSOnAuthError` helper adds the appropriate `Access-Control-Allow-Origin` header so that browsers can properly read the error response rather than receiving a network error.

### Can I disable authentication for local development?

Yes. Set `require_auth` to `false` via the configuration file, environment variables, or the `/api/v1/settings` endpoint. When disabled, most API endpoints under `/api/` are accessible without tokens, though remote-sync routes still require authentication to establish the remote context and enable machine-to-machine synchronization.

### How is the authentication token stored and configured?

The token is stored in the server configuration structure (`cfg.AuthToken`) alongside the `RequireAuth` boolean. These values are initialized in [`cmd/agentsview/main.go`](https://github.com/kenn-io/agentsview/blob/main/cmd/agentsview/main.go) from CLI flags or environment variables, and can be updated dynamically through the settings API without restarting the server.