> ## Documentation Index
> Fetch the complete documentation index at: https://doc.rapida.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Web API

> Core platform backend. Handles authentication, organization management, credential vault, and acts as the gRPC proxy for all dashboard operations.

## 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.

> [card] Port
>
> `9001` — HTTP · gRPC · gRPC-web (cmux)

> [card] Language
>
> Go 1.25
> Gin (REST) + gRPC

> [card] Storage
>
> PostgreSQL `web_db`
> Redis (session cache)

***

## Request Flow

```mermaid theme={null}
sequenceDiagram
    participant Browser as Browser (Dashboard)
    participant Nginx as Nginx :8080
    participant Web as web-api :9001
    participant PG as PostgreSQL (web_db)
    participant Redis as Redis
    participant DS as Downstream Service

    Browser->>Nginx: gRPC-web POST /<service>_api.*
    Nginx->>Web: Forward (all non-talk_api paths)
    Web->>Web: JWT interceptor — validate token
    Web->>PG: Check organization + project scope
    alt Local service
        Web->>PG: Execute operation
        Web->>Redis: Update cache
    else Downstream proxy
        Web->>DS: gRPC forward with org context
        DS-->>Web: Response
    end
    Web-->>Browser: gRPC-web response
```

***

## Core Components

> [accordion] 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 |

> [accordion] 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`.

> [accordion] 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 |

> [accordion] 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 |

> [accordion] Database Migrations
>
> Migrations run automatically at service startup using [golang-migrate](https://github.com/golang-migrate/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:
>
> ```bash theme={null}
> 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

> [tab] Docker Compose
>
> ```bash theme={null}
> make up-web
>
> make logs-web
>
> make rebuild-web
>
> make shell-web
> ```

> [tab] From Source
>
> Requires Go 1.25, PostgreSQL 15, and Redis 7 running locally.
>
> ```bash theme={null}
> 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 |

```bash theme={null}
curl http://localhost:9001/readiness/
```

***

## Troubleshooting

> [accordion] Service exits immediately on startup
>
> The most common cause is PostgreSQL not yet healthy.
>
> ```bash theme={null}
> docker compose ps postgres
> make logs-web | head -40
> ```

> [accordion] 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`.

> [accordion] 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

> [card] [Configuration](https://doc.rapida.ai/opensource/services/web-api/configuration.md)
>
> All environment variables and internal service addresses.

> [card] [Assistant API](https://doc.rapida.ai/opensource/services/assistant-api/overview.md)
>
> Voice orchestration service that web-api proxies to.

> [card] [Integration API](https://doc.rapida.ai/opensource/services/integration-api/overview.md)
>
> Provider credential management.

> [card] [Architecture](https://doc.rapida.ai/opensource/architecture.md)
>
> Full system topology and routing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.