Portal Implementation Notes

Last updated: 2026-06-28

Portal and the API gateway provide hosted API access, API keys, usage tracking, billing surfaces, and managed router-pool forwarding.

Product Shape

Surface	Current behavior
Portal app	Vite/React app with auth, layout, usage, API keys, billing, docs, and profile pages.
Key management	Gateway can create, list, and revoke keys through local mode or Unkey.
Usage events	Gateway records usage and Portal reads summaries.
Customer completions	/v1/completions resolves model/router pool/session settings and forwards to router /api/v3/completions.
Router pool mapping	Env-driven model alias to router pool URL.
Session routing	Env-driven model-to-session and session/model auth key maps.

V1 Architecture

Portal V1 combines:

Clerk or Supabase Auth + Supabase DB + Unkey + custom Portal backend + managed Cortensor router pools

That architecture maps to the product components this way:

V1 component	Product behavior
Auth	Portal app has account/profile surfaces; final provider boundary is environment-specific.
Supabase DB	Usage and key metadata are stored/read through configured Supabase paths.
Unkey	Gateway supports hosted key issuing/revocation when PORTAL_UNKEY_* is configured.
Custom backend/gateway	FastAPI gateway verifies keys, maps models, forwards completions, and records usage.
Router pools	Gateway maps product-facing model aliases to router pool URLs and sessions.

Request Path

sequenceDiagram
  participant Dev as Developer
  participant Portal as Portal Web App
  participant Gateway as API Gateway
  participant Keys as Key Issuer
  participant Router as Managed Router Pool
  participant Usage as Supabase Usage

  Dev->>Portal: create key / inspect usage
  Portal->>Gateway: management request
  Gateway->>Keys: create or revoke key
  Dev->>Gateway: POST /v1/completions
  Gateway->>Gateway: verify key and rate limit
  Gateway->>Router: POST /api/v3/completions/{session_id}
  Router-->>Gateway: router response
  Gateway->>Usage: record status and latency
  Gateway-->>Dev: request_id, model, router_pool, data

Deployment Values

Item	Public value
Auth provider	The production provider used for account/session auth.
API key issuer	The key issuer and revocation path exposed to customers.
Free plan limits	Quotas, rate limits, and billing policy.
Model aliases	Customer-facing model names backed by router pools.
Router auth	How the gateway authenticates to managed router pools.
Usage schema	Usage fields shown to customers and retained for billing/support.
Error envelope	Public error codes, request IDs, and retry guidance.

Product Boundary

Portal is a hosted developer product. It is separate from the protocol, miner network, and Corgent service wrapper.