Web API

Purpose

The web-api is the primary API backend for the Rapida dashboard. Every request from the browser — authentication, organization setup, assistant management, credential storage — goes through this service. It also acts as the gRPC proxy for downstream services, validating JWT tokens before forwarding requests.

Port

9001 — HTTP · gRPC · gRPC-web (cmux)

Language

Go 1.25 Gin (REST) + gRPC

Storage

PostgreSQL web_db Redis (session cache)

Request Flow

Core Components

Authentication & Session Management

Handles user registration, login, password recovery, OAuth 2.0, and JWT issuance.

Feature	Detail
Token type	JWT (signed with `SECRET`, shared across all services)
Token storage	Client-side (`Authorization` header)
Session cache	Redis DB 1
OAuth providers	Google, GitHub, Microsoft (configured per deployment)
Token expiry	Default 24 hours

Organization & Project Hierarchy

Every resource in Rapida is scoped to an Organization → Project hierarchy. The web-api enforces this at the gRPC interceptor level.

Organization
└── Project
    ├── Assistants
    ├── Knowledge Bases
    ├── Integrations
    └── Webhooks

The gRPC auth interceptor rejects any request where the JWT’s organization claim does not match the target resource’s organization_id.

Credential Vault

Provider API keys are encrypted with AES-256-GCM before storage. The encryption key is derived from SECRET.

Operation	Behavior
Store key	AES-256-GCM encrypt → write to `web_db`
Retrieve key	Read → decrypt in-memory → forward to `integration-api`
Rotate key	Replace ciphertext; in-flight calls unaffected
Audit	Every read/write logged with user ID and timestamp

gRPC Proxy Routing

The web-api proxies all dashboard gRPC calls after JWT validation:

gRPC Path Prefix	Forwarded To
`/web_api` · `/vault_api`	Local (web-api)
`/workflow_api` · `/assistant_api` · `/knowledge_api`	`assistant-api:9007`
`/tool_api` · `/endpoint_api` · `/webhook_api`	`endpoint-api:9005`
`/provider_api` · `/integration_api`	`integration-api:9004`
`/document_api`	`document-api:9010`
`/connect_api`	Local (OAuth connector)
`/talk_api`	Direct to `assistant-api` via Nginx — not proxied through web-api

Database Migrations

Migrations run automatically at service startup using golang-migrate. Migration files are in api/web-api/migrations/:

000001_initial_schema.up.sql
000001_initial_schema.down.sql
000002_add_oauth_tokens.up.sql

To run migrations manually:

go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

migrate \
  -path api/web-api/migrations \
  -database "postgresql://rapida_user:rapida_db_password@localhost:5432/web_db?sslmode=disable" \
  up

Running

Docker Compose
From Source

make up-web

make logs-web

make rebuild-web

make shell-web

Requires Go 1.25, PostgreSQL 15, and Redis 7 running locally.

export $(grep -v '^#' docker/web-api/.web.env | xargs)
export POSTGRES__HOST=localhost
export REDIS__HOST=localhost
export INTEGRATION_HOST=localhost:9004
export ENDPOINT_HOST=localhost:9005
export ASSISTANT_HOST=localhost:9007
export DOCUMENT_HOST=http://localhost:9010

go run cmd/web/web.go

Health Endpoints

Endpoint	Purpose
`GET /readiness/`	Service ready (DB + Redis connected)
`GET /healthz/`	Liveness probe

curl http://localhost:9001/readiness/

Troubleshooting

Service exits immediately on startup

The most common cause is PostgreSQL not yet healthy.

docker compose ps postgres
make logs-web | head -40

JWT validation fails across services

All services must share the same secret value. Confirm secret is identical in docker/web-api/web.yml, docker/assistant-api/assistant.yml, docker/integration-api/integration.yml, and docker/endpoint-api/endpoint.yml.

gRPC proxy returns 'service unavailable'

The target downstream service must be running and healthy. Verify INTEGRATION_HOST, ENDPOINT_HOST, ASSISTANT_HOST point to reachable addresses. Check make status to confirm all containers are Up.

Next Steps

Configuration

All environment variables and internal service addresses.

Assistant API

Voice orchestration service that web-api proxies to.

Integration API

Provider credential management.

Architecture

Full system topology and routing.

Getting Started

Dashboard (UI)

Assistant API

Integration API

Endpoint API

Document API

Web API

Purpose

Port

Language

Storage

Request Flow

Core Components

Running

Health Endpoints

Troubleshooting

Next Steps

Configuration

Assistant API

Integration API

Architecture

​Purpose

Port

Language

Storage

​Request Flow

​Core Components

​Running

​Health Endpoints

​Troubleshooting

​Next Steps

Configuration

Assistant API

Integration API

Architecture

Purpose

Request Flow

Core Components

Running

Health Endpoints

Troubleshooting

Next Steps