# How to Implement Optional Authentication in OmniRoute: A Complete Guide

> Learn how to implement optional authentication in OmniRoute. Control access with the requireLogin flag for flexible security in your application.

- Repository: [Diego Rodrigues de Sa e Souza/OmniRoute](https://github.com/diegosouzapw/OmniRoute)
- Tags: how-to-guide
- Published: 2026-08-23

---

**Optional authentication in OmniRoute is controlled by the `requireLogin` runtime flag stored in [`src/lib/db/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts); when set to `false`, management-tier routes accept unauthenticated requests while always-protected routes remain secured.**

Optional authentication in the **diegosouzapw/OmniRoute** repository is governed by a runtime boolean that toggles credential enforcement on standard API routes. When disabled, the authorization pipeline permits anonymous access to most endpoints while maintaining mandatory authentication for destructive operations. This architecture allows administrators to deploy open-access instances without sacrificing security for critical system functions.

## Understanding the Three-Tier Authorization Model

OmniRoute classifies every incoming request into one of three distinct authorization tiers defined in [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts):

**LOCAL-ONLY**: Routes that spawn child processes or execute system commands. These endpoints automatically reject connections from non-loopback network interfaces, regardless of authentication status or the `requireLogin` setting.

**ALWAYS-PROTECTED**: Destructive endpoints that mandate valid authentication even when the global `requireLogin` flag is disabled. This tier is enforced by the `isAlwaysProtectedPath` function (lines 78-80) against the `ALWAYS_PROTECTED_API_PATHS` constant.

**MANAGEMENT**: Standard API routes that respect the runtime `requireLogin` boolean. When this flag is `false`, these routes operate in optional authentication mode, accepting both authenticated and anonymous requests while still validating tokens when present.

The `runAuthzPipeline` function orchestrates these checks for every request entering the Next.js route handlers.

## Configuring the requireLogin Runtime Flag

The core mechanism resides in the settings database. The `requireLogin` boolean defaults to `true` but can be toggled to enable optional authentication:

```typescript
// src/lib/db/settings.ts (lines 61-65)
// https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/lib/db/settings.ts#L61-L65
requireLogin: true,

```

Changes to this value are applied live through [`src/lib/config/runtimeSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/config/runtimeSettings.ts), which updates the in-memory authorization pipeline without requiring a server restart. When `requireLogin` is `false`, the `runAuthzPipeline` skips credential validation for management-tier routes while still enforcing protection for local-only and always-protected paths.

## Creating Routes with Optional Authentication

To implement an endpoint that respects the optional authentication setting, create your route handler in `src/app/api/v1/` and avoid adding it to the protected lists. The pipeline automatically evaluates the `requireLogin` flag before your handler executes.

**Example: Anonymous-Compatible GET Endpoint**

```typescript
// src/app/api/v1/status/route.ts
import { getSettings } from "@/lib/db/settings";

export async function GET(request: Request) {
  const { requireLogin } = await getSettings();
  
  if (requireLogin) {
    // The authz pipeline has already verified the request
    const userId = request.headers.get("x-omniroute-user-id");
    return Response.json({ status: "ok", user: userId });
  }
  
  // Optional auth mode: treat as anonymous
  return Response.json({ status: "ok", user: "anonymous" });
}

```

**Example: Conditional POST Handler**

```typescript
// src/app/api/v1/feedback/route.ts
import { getSettings } from "@/lib/db/settings";

export async function POST(request: Request) {
  const { requireLogin } = await getSettings();
  const body = await request.json();
  
  const author = requireLogin
    ? request.headers.get("x-omniroute-user-id") ?? "unknown"
    : "anonymous";
    
  // Process feedback...
  return new Response(`Recorded from ${author}`, { status: 201 });
}

```

## Protecting Critical Routes

Destructive operations remain protected regardless of the `requireLogin` setting. These endpoints are listed in the `ALWAYS_PROTECTED_API_PATHS` array in [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts):

```typescript
// src/server/authz/routeGuard.ts (lines 20-28)
// https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/server/authz/routeGuard.ts#L20-L28
export const ALWAYS_PROTECTED_API_PATHS: ReadonlyArray<string> = [
  "/api/shutdown",
  "/api/providers/health-autopilot/actions",
  "/api/settings/database",
  "/api/db-backups",
];

```

The `isAlwaysProtectedPath` function (lines 78-80) evaluates incoming requests against this list:

```typescript
// src/server/authz/routeGuard.ts (lines 78-80)
// https://github.com/diegosouzapw/OmniRoute/blob/release/v3.8.50/src/server/authz/routeGuard.ts#L78-L80
export function isAlwaysProtectedPath(path: string) {
  return ALWAYS_PROTECTED_API_PATHS.some(p => path === p || path.startsWith(p));
}

```

To permanently protect a new route, add its exact path or prefix to the `ALWAYS_PROTECTED_API_PATHS` array.

## Manage-Scope Bypass for Local-Only Routes

Local-only routes (such as those spawning processes) typically reject remote connections. However, OmniRoute supports a **manage-scope bypass** allowing remote access when clients present valid management API keys.

This behavior is controlled by settings in [`src/lib/db/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts) (lines 22-30):

- `localOnlyManageScopeBypassEnabled`: Boolean toggle (default `true`)
- `localOnlyManageScopeBypassPrefixes`: Array of path prefixes (default `["/api/mcp/"]`)

The `isLocalOnlyBypassableByManageScope` function in [`routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/routeGuard.ts) checks these values. If you need remote authenticated access to a local-capable endpoint while keeping `requireLogin` optional, add its prefix to the bypass list.

## Summary

- OmniRoute uses a **three-tier authorization model** (Local-Only, Always-Protected, Management) defined in [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts).
- The **`requireLogin` flag** in [`src/lib/db/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts) controls whether management routes require authentication; changes apply live via [`src/lib/config/runtimeSettings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/config/runtimeSettings.ts).
- When `requireLogin` is `false`, routes not listed in `ALWAYS_PROTECTED_API_PATHS` accept unauthenticated requests.
- Add critical endpoints to **`ALWAYS_PROTECTED_API_PATHS`** to enforce authentication regardless of the runtime setting.
- Use **`localOnlyManageScopeBypassEnabled`** and **`localOnlyManageScopeBypassPrefixes`** to allow remote authenticated access to local-only routes via management API keys.

## Frequently Asked Questions

### How do I completely disable authentication in OmniRoute?

Set `requireLogin` to `false` in [`src/lib/db/settings.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/lib/db/settings.ts) (line 63). This allows anonymous access to all management-tier routes while preserving protection for always-protected paths and maintaining local-only restrictions. Destructive endpoints like `/api/shutdown` will still reject unauthenticated requests.

### What is the difference between local-only and always-protected routes?

**Local-only routes** block remote connections entirely based on network interface, regardless of credentials, to prevent remote code execution. **Always-protected routes** accept remote connections but mandate valid authentication even when `requireLogin` is disabled, protecting destructive operations like database modifications or server shutdown.

### How do I make a custom route permanently require authentication?

Add the route path to the `ALWAYS_PROTECTED_API_PATHS` array in [`src/server/authz/routeGuard.ts`](https://github.com/diegosouzapw/OmniRoute/blob/main/src/server/authz/routeGuard.ts). The `isAlwaysProtectedPath` function automatically enforces authentication on these endpoints regardless of the global `requireLogin` setting.

### Can remote users access local-only routes with special permissions?

Yes. When `localOnlyManageScopeBypassEnabled` is `true` (default), remote clients presenting a valid management-scope API key can access routes matching prefixes in `localOnlyManageScopeBypassPrefixes` (default: `["/api/mcp/"]`). This bypass is evaluated by `isLocalOnlyBypassableByManageScope` before the local-only check rejects the request.