Testing Services Locally

When you deploy a service to Forte, every request flows through the Forte API gateway — this is where user authentication, session validation, and request authorization happen. But when you're developing locally, your service runs on localhost without the gateway in front of it.

The Forte CLI proxy bridges this gap. It runs a local server that intercepts requests, sends them to the Forte gateway for authorization, and forwards authorized requests to your local service with the authenticated user context attached.

How It Works

  Your App (browser/client)
          │
          ▼
  forte proxy (localhost:8080)
          │
          ├── Sends request metadata to Forte Gateway
          │   (path, method, headers, cookies)
          │
          ├── Gateway validates session token
          │   and returns augmented headers
          │
          ▼
  Your Local Service (localhost:3000)
          receives request with user context

For each incoming request, the proxy:

1. Extracts the request path, HTTP method, and headers (including cookies)
2. Sends them to the Forte gateway's authorization endpoint
3. If authorization fails — returns the error directly to the client (401, 403, etc.)
4. If authorization succeeds — forwards the request to your local service with augmented headers containing the authenticated user's context

Prerequisites

• Forte CLI installed
• Authenticated with forte login
• A project with at least one service created in Forte
• Your service running locally

Step 1: Start Your Local Service

Start your service on its usual port. For example, if your app runs on port 3000:

# Whatever your normal start command is
npm run dev
# or
python manage.py runserver 3000
# or
go run main.go

Step 2: Start the Forte Proxy

In a separate terminal, run:

forte proxy

The CLI will interactively prompt you to select a project and service. Once selected, the proxy starts and shows:

✓ Proxy running
 
Project: my-app (abc-123)
Service: api-service (def-456)
 
Proxy URL:     http://localhost:8080
Forwarding to: http://localhost:3000
 
Press Ctrl+C to stop

Specifying Options Directly

You can skip the interactive prompts by passing flags:

forte proxy --project-id <project-id> --service-id <service-id>

If your service runs on a port other than 3000, use the -p flag:

forte proxy -p 4000

To change the proxy's listen port (default is 8080):

forte proxy --proxy-port 9000

Step 3: Point Your Client at the Proxy

Instead of sending requests directly to http://localhost:3000, point your frontend or API client at the proxy URL — by default http://localhost:8080.

For example, if your frontend normally calls your API at https://my-app.tryforte.dev, change the base URL in your local environment to http://localhost:8080.

The proxy handles everything transparently — your local service receives requests exactly as it would in production, with the same headers and user context.

User Authentication Flow

Here's how end-user authentication works through the proxy:

1. User logs in through your app's authentication flow (Google OAuth, email/phone verification, etc.)
2. Forte issues a session token stored as a Forte-User-Session-Token cookie in the user's browser
3. Browser sends requests to the proxy with the session cookie attached
4. Proxy forwards the cookie to the Forte gateway, which validates the session token and identifies the user
5. Gateway returns augmented headers containing the user's identity and authorization context
6. Proxy forwards the request to your local service with these augmented headers

Your local service receives the same user context it would get in production — no mocking or stubbing required.

Monitoring Requests

While the proxy is running, it displays a live log of recent requests:

Recent Requests (3):
  10:32:15 ✓ GET  /api/health 200
  10:32:14 ✓ POST /api/data   201
  10:32:12 ✗ GET  /api/admin  401

Each entry shows:

• Timestamp of the request
• Authorization status — ✓ (authorized and forwarded) or ✗ (rejected by gateway)
• HTTP method and path
• Response status code

This makes it easy to spot authentication issues during development.