# How to Access the FreeLLMAPI Admin Dashboard: Complete Setup and Login Guide

> Access the FreeLLMAPI admin dashboard easily. This guide covers setup and login on port 3001, ensuring you get to your account creation or login screen quickly.

- Repository: [Tashfeen/freellmapi](https://github.com/tashfeenahmed/freellmapi)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The FreeLLMAPI admin dashboard runs on port 3001 by default and automatically detects first-run setup through the `/api/auth/status` endpoint, presenting either an account creation form or login screen based on your server state.**

FreeLLMAPI provides a **React-based admin dashboard** that ships alongside the router server, giving you full control over API keys, provider routing, and analytics through a web interface. This guide walks you through accessing the dashboard based on how it's implemented in the tashfeenahmed/freellmapi source code, from initial setup to daily administration.

## Understanding the Dashboard Architecture

The dashboard consists of two tightly integrated components:

- **Express server** ([`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts)) — Serves static UI files and exposes `/api/*` admin endpoints
- **React SPA** ([`client/src/main.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/src/main.tsx)) — Boots the interface and handles authentication flows

All admin functionality routes through [`server/src/routes/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts), which implements session-based authentication using signed cookies or Bearer tokens passed in the `Authorization` header.

## Starting the Server

Before accessing the dashboard, ensure your FreeLLMAPI router is running:

```bash

# Docker Compose (recommended)

docker-compose up -d

# Or local development

npm run dev  # in server/ directory

```

By default, the server listens on **port 3001**. The dashboard becomes available immediately once the process starts.

## First-Run Setup: Creating the Admin Account

When no dashboard users exist, FreeLLMAPI detects this state and requires initial setup. The **status endpoint** at `GET /api/auth/status` returns `needsSetup: true` in this case, triggering the setup flow in the UI.

### Verify Setup Requirement (API)

```bash
curl -s http://localhost:3001/api/auth/status | jq .

```

```json
{
  "needsSetup": true,
  "authenticated": false,
  "email": null
}

```

Source reference: [`server/src/routes/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts) lines 73-80 implement this check against the user database.

### Create the Initial Admin Account

The **setup endpoint** (`POST /api/auth/setup`) creates the first admin account. For local access, no additional verification is required:

```bash
curl -X POST http://localhost:3001/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123"}' \
  | jq .

```

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "email": "admin@example.com"
}

```

### Remote Setup with Verification Code

If accessing from a remote host (detected by IP), the server requires a **one-time setup code** printed to the server logs:

```bash

# First, check logs for setup code

docker logs freellmapi-server  # look for: "Setup code: ABCD-EFGH-1234"

# Then include it in your request

curl -X POST http://localhost:3001/api/auth/setup \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123","setupCode":"ABCD-EFGH-1234"}' \
  | jq .

```

Source reference: [`server/src/routes/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts) lines 83-96 implement this security measure.

## Logging Into an Existing Dashboard

For subsequent access, use the **login endpoint** (`POST /api/auth/login`):

```bash
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123"}' \
  | jq .

```

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…",
  "email": "admin@example.com"
}

```

## Using the Web Interface

### Browser Access

Navigate directly to the server root:

```bash
open http://localhost:3001   # macOS

# or manually enter http://localhost:3001 in any browser

```

The **`AuthGate`** component ([`client/src/components/auth-gate.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/src/components/auth-gate.tsx) lines 29-71) immediately queries `/api/auth/status` and renders the appropriate form:

- **Setup mode** — Shows "Create your account" form posting to `/api/auth/setup`
- **Login mode** — Shows email/password form posting to `/api/auth/login`

Upon successful authentication, `setToken` stores the session and the full dashboard renders with navigation to keys, routing rules, and analytics.

### Making Authenticated API Calls

Extract and use your token for programmatic access:

```bash
TOKEN=$(curl -s -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"SuperSecret123"}' | jq -r .token)

curl -H "Authorization: Bearer $TOKEN" http://localhost:3001/api/keys | jq .

```

## Key Implementation Files

Understanding these source files helps troubleshoot access issues:

| File | Purpose |
|------|---------|
| [`server/src/routes/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts) | Authentication endpoints: status, setup, login, logout |
| [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) | Mounts admin router and static file serving |
| [`client/src/components/auth-gate.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/src/components/auth-gate.tsx) | React auth gate with setup/login form logic |
| [`client/src/main.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/src/main.tsx) | Dashboard SPA entry point |
| [`docs/architecture.md`](https://github.com/tashfeenahmed/freellmapi/blob/main/docs/architecture.md) | High-level auth and routing documentation |

## Troubleshooting Common Access Issues

### Dashboard shows 404

Verify the server built the client assets. The Express app serves static files from the client build directory—run `npm run build` in the `client/` folder if developing locally.

### Remote access blocked

Check for setup code requirement in server logs. The IP detection in [`auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/auth.ts) requires verification codes for non-local hosts.

### Session expires immediately

Ensure `JWT_SECRET` is set in your environment. Session tokens are signed with this secret; missing configuration causes immediate invalidation.

## Summary

- **FreeLLMAPI admin dashboard** runs at `http://localhost:3001` by default, served by the same Express process handling API requests
- **First-run detection** via `/api/auth/status` automatically guides you through account creation
- **Authentication** supports both session cookies and `Authorization: Bearer` tokens for API access
- **Remote setup security** requires a one-time code from server logs when accessing from external IPs
- **`AuthGate` component** in [`client/src/components/auth-gate.tsx`](https://github.com/tashfeenahmed/freellmapi/blob/main/client/src/components/auth-gate.tsx) orchestrates the UI flow between setup and login states

## Frequently Asked Questions

### How do I reset a forgotten admin password?

FreeLLMAPI does not implement automated password recovery in the open-source version. You must access the server filesystem directly to reset credentials, or redeploy with fresh state. Check [`server/src/routes/auth.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/routes/auth.ts) for the user storage mechanism—typically SQLite or your configured database.

### Can I run the dashboard on a different port?

Yes. The port is configured through environment variables in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts). Set `PORT=3002` or your preferred value before starting the server, then access the dashboard at that port.

### Is HTTPS supported for the admin dashboard?

The Express server in [`server/src/app.ts`](https://github.com/tashfeenahmed/freellmapi/blob/main/server/src/app.ts) handles HTTP by default. For production HTTPS, deploy behind a reverse proxy (nginx, Traefik, Caddy) or modify the server bootstrap code to provide TLS certificates directly.

### What's the difference between dashboard authentication and API key authentication?

Dashboard auth (session tokens via `/api/auth/login`) grants administrative access to configure providers and routing. API key authentication (passed to `/v1/chat/completions`) controls access to the LLM inference endpoints. These systems are separate—dashboard users manage API keys that external clients use.