Testing services locally

In production, requests to a Service pass through the Forte API gateway for authentication. When you develop locally, your code runs without that gateway.

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

For each incoming request, the proxy:

1. Extracts the request path, HTTP method, and headers (including cookies)
2. Authorizes them identically to how the Forte API Gateway would
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 prompts you to select a project and service. The proxy then 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

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.

Your local service receives the same Forte headers and user context as it does in production.

User authentication flow

End-user authentication works through the proxy like this:

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 runs, 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

Use this log to spot authentication issues during development.