# How to Manage Users in Pi-Web: Single-User Architecture and External Provider Authentication

> Learn how to manage users in Pi-Web. Discover its single-user architecture, OS-level permissions, and external provider authentication for secure access control.

- Repository: [Alex Yang/pi-web](https://github.com/agegr/pi-web)
- Tags: how-to-guide
- Published: 2026-07-27

---

**Pi-Web operates as a single-user local application without built-in user account management, relying instead on OS-level permissions for access control and dedicated API routes to manage external AI provider credentials.**

Pi-Web, developed by `agegr/pi-web`, is a local front-end for the Pi AI engine designed to run under a single operating system user. Unlike traditional web applications, managing users in Pi-web does not involve creating internal accounts or permissions databases. Instead, user management focuses on securing access to the host system and administering credentials for external AI providers through specific authentication endpoints.

## Understanding Pi-Web's Single-User Architecture

Pi-Web does not implement a multi-user system or maintain a database of user accounts. The only "user" concept in the codebase appears as the **message role** (e.g., `user`, `assistant`) used to distinguish human input from AI output in conversation threads. In [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts), the application tracks messages where `msg.role === "user"` to drive UI updates and session statistics defined in [`lib/pi-types.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-types.ts), but these represent conversation participants rather than authenticated accounts.

The application runs under the current operating system user, with all filesystem access and process permissions governed by the OS itself. This design eliminates the need for internal user management but requires administrators to control access at the system level.

## Managing External AI Provider Credentials

Since Pi-Web delegates authentication to external AI services, managing users effectively means managing these provider connections. The application stores and accesses provider credentials through dedicated API routes under `/api/auth`.

### Storing API Keys

The `app/api/auth/api-key/[provider]/route.ts` endpoint handles adding, retrieving, and deleting API-key credentials. To store a new key:

```http
POST /api/auth/api-key/openai
Content-Type: application/json

{
  "apiKey": "sk‑YOUR_OPENAI_KEY"
}

```

### OAuth Authentication Flow

For providers supporting OAuth, the `app/api/auth/login/[provider]/route.ts` implements the device-code flow. Initiate authentication with:

```http
POST /api/auth/login/openai

```

### Checking Provider Status

Verify which providers are configured and their authentication status using the [`app/api/auth/all-providers/route.ts`](https://github.com/agegr/pi-web/blob/main/app/api/auth/all-providers/route.ts) endpoint:

```http
GET /api/auth/all-providers

```

### Revoking Credentials

Remove stored API keys when access should be terminated:

```http
DELETE /api/auth/api-key/openai

```

## Security Controls and Request Validation

While Pi-Web lacks internal user accounts, it implements security through [`lib/request-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/request-security.ts), which validates that only allowed origins and request parameters are accepted. This prevents unauthorized requests to the authentication endpoints. All credential storage occurs locally on the machine, protected by the operating system's filesystem permissions rather than application-layer access controls.

## Extending Pi-Web for Multi-User Environments

If your deployment requires true multi-user functionality with separate login accounts, Pi-Web requires additional infrastructure. You must implement a reverse proxy with authentication or a custom wrapper that stores per-user session data externally. The base application in `agegr/pi-web` assumes single-operator use and does not provide hooks for user isolation or session management between distinct human users.

## Summary

- Pi-Web operates as a **single-user application** without internal user account databases or multi-user authentication.
- **OS-level permissions** control access to the application and its data, as the server runs under the current system user.
- External AI credentials are managed via `/api/auth` endpoints in `app/api/auth/api-key/[provider]/route.ts` and `app/api/auth/login/[provider]/route.ts`.
- The **message role** concept in [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) tracks conversation participants for UI purposes, not authenticated users.
- **Multi-user setups** require external infrastructure such as reverse proxies with authentication layers.

## Frequently Asked Questions

### Does Pi-Web support multiple user accounts?

No, Pi-Web does not implement a multi-user system or user account database. It runs as a single-user local application under the current operating system user, tracking only message roles (`user` vs `assistant`) in [`lib/pi-types.ts`](https://github.com/agegr/pi-web/blob/main/lib/pi-types.ts) for conversation context rather than authentication.

### Where are AI provider credentials stored in Pi-Web?

Credentials are stored and managed through the API routes defined in `app/api/auth/api-key/[provider]/route.ts` for API keys and `app/api/auth/login/[provider]/route.ts` for OAuth flows. The [`lib/request-security.ts`](https://github.com/agegr/pi-web/blob/main/lib/request-security.ts) module validates all incoming requests to these endpoints, while the actual credential data resides on the local filesystem protected by OS permissions.

### How do I secure Pi-Web if multiple people use the same computer?

Since Pi-Web relies on OS-level access controls rather than application-layer user management, secure the host system by restricting which operating system users can execute the server or access the application directory. For network deployments requiring distinct user sessions, place Pi-Web behind a reverse proxy with authentication to handle multi-user access before requests reach the application.

### What is the difference between the "user" role and user accounts in Pi-Web?

The "user" role in Pi-Web refers to the message type tracked in [`hooks/useAgentSession.ts`](https://github.com/agegr/pi-web/blob/main/hooks/useAgentSession.ts) to distinguish human input from AI responses in conversation statistics. This is purely a conversation construct used for UI updates and session metrics, not an authentication or account management feature.