Skip to main content

​
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

Handles user registration, login, password recovery, OAuth 2.0, and JWT issuance.
FeatureDetail
Token typeJWT (signed with SECRET, shared across all services)
Token storageClient-side (Authorization header)
Session cacheRedis DB 1
OAuth providersGoogle, GitHub, Microsoft (configured per deployment)
Token expiryDefault 24 hours
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.
Provider API keys are encrypted with AES-256-GCM before storage. The encryption key is derived from SECRET.
OperationBehavior
Store keyAES-256-GCM encrypt → write to web_db
Retrieve keyRead → decrypt in-memory → forward to integration-api
Rotate keyReplace ciphertext; in-flight calls unaffected
AuditEvery read/write logged with user ID and timestamp
The web-api proxies all dashboard gRPC calls after JWT validation:
gRPC Path PrefixForwarded To
/web_api · /vault_apiLocal (web-api)
/workflow_api · /assistant_api · /knowledge_apiassistant-api:9007
/tool_api · /endpoint_api · /webhook_apiendpoint-api:9005
/provider_api · /integration_apiintegration-api:9004
/document_apidocument-api:9010
/connect_apiLocal (OAuth connector)
/talk_apiDirect to assistant-api via Nginx — not proxied through web-api
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

make up-web

make logs-web

make rebuild-web

make shell-web

​
Health Endpoints

EndpointPurpose
GET /readiness/Service ready (DB + Redis connected)
GET /healthz/Liveness probe
curl http://localhost:9001/readiness/

​
Troubleshooting

The most common cause is PostgreSQL not yet healthy.
docker compose ps postgres
make logs-web | head -40
All services must share the same SECRET value. Confirm it is identical in .web.env, .assistant.env, .integration.env, and .endpoint.env.
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.