Cortensor Portal V1 Backend, Data Model, and Gateway Specification

Status

Draft

Purpose

This document is the first implementation-oriented backend reference for Cortensor Portal V1.

It focuses on:

• what should be stored in Supabase

• what should be delegated to Unkey

• what logic belongs in the Portal API gateway/backend

• how requests should flow from API key to managed Cortensor router nodes

• how durable usage, request, and billing state should be written

This is a product-backend spec, not a router-node implementation spec.

---

1. Summary

Portal V1 should be built around a custom Portal backend / gateway that sits between customers and managed Cortensor router pools.

The Portal backend is the product boundary and should own:

• request authentication

• model entitlement checks

• quota interpretation

• router-pool selection

• request normalization

• response normalization

• usage event emission

• durable write coordination

The public shape is not:

client -> Unkey -> router

It is:

client
  -> Portal API gateway/backend
  -> Unkey verification + rate limit
  -> Supabase-backed product logic
  -> managed router pool
  -> Cortensor router node
  -> dedicated-backed session

The key idea is:

The gateway is the product boundary. It owns authentication, quota, entitlement, routing, and metering semantics, while router nodes remain the backend inference layer.

---

2. Goals

The backend, durable state, and gateway design should aim to:

• centralize Cortensor-specific business logic

• keep the external API stable while the router fleet evolves

• support quota, entitlement, and routing logic in one owned layer

• support durable usage and billing write coordination

• keep customer-facing request behavior productized

• avoid requiring many raw database reads in the hot path

• preserve room for future paid plans, credits, and richer routing

---

3. Scope

In Scope

• Supabase-backed durable Portal product state

• Unkey-backed key verification and rate limit support

• custom Portal backend and request gateway

• router-pool selection logic

• request and response normalization

• durable usage and request logging

• simple V1 billing foundations

• basic operational/admin readiness

Out of Scope

• customer-facing raw router or session control

• direct exposure of router-node URLs

• prompt/response retention by default

• complex billing dimensions on day one

• advanced autoscaling control plane

• Kubernetes-native fleet orchestration as a requirement for V1

• customer-managed sessions

---

4. Core Backend Shape

Portal V1 should not expose raw router nodes directly to customers.

The public path should be:

customer app
  -> Portal API gateway/backend
  -> Unkey verification + rate limit
  -> Supabase-backed product logic
  -> managed router pool
  -> Cortensor router node
  -> dedicated-backed session

Layer Responsibilities

Auth Layer

Owns:

• user login

• web session identity

• auth provider identity bridge

Product Data Layer

Owns:

• users

• organizations

• API key metadata

• plan and entitlement data

• usage and billing records

• router pool metadata

Gateway / Control Plane

Owns:

• request-time product logic

• key verification coordination

• model entitlement checks

• quota checks

• routing

• normalization

• usage emission

Inference Layer

Owns:

• router pools

• router node health

• actual inference execution

• dedicated-backed sessions

---

5. Responsibility Split

5.1 Clerk or Auth Provider

Use Clerk (or the final chosen auth provider) for interactive web app identity.

Auth provider should own:

• user login

• email/social/wallet auth if enabled

• hosted auth UI/session handling

• auth-provider user ID

• organization membership if provider-native orgs are used

Auth provider should not be the source of truth for:

• Portal billing

• usage state

• model access policy

• router pools

• request logs

Those are Portal-owned product concerns.

---

5.2 Supabase

Use Supabase as the durable product and control-plane database.

Supabase should store:

• Portal users

• organizations

• memberships

• API key metadata

• plans and entitlements

• model catalog and model access policy

• quota policy definitions

• usage events and usage rollups

• billing ledger

• router pool metadata

• request logs

• operational audit data

Important constraint:

• Supabase is the source of truth

• Supabase should not be the only hot-path enforcement dependency for every request

Hot-path fields should be cached or denormalized where practical.

---

5.3 Unkey

Use Unkey for API key primitives.

Unkey should own or support:

• API key issuance or key material

• API key verification

• revocation-aware validation

• per-key rate limiting

• basic key-level analytics

Unkey should not own:

• model entitlement rules

• plan semantics

• billing semantics

• router pool selection

• durable usage ledger

• request normalization

• response normalization

Unkey is a supporting enforcement layer, not the full product control plane.

---

5.4 Portal API Gateway / Backend

The Portal backend is required even in V1.

It should own:

• validating customer API requests

• calling Unkey to verify API keys

• loading or caching key/org/product metadata

• checking model access

• checking quota allowance

• resolving product model aliases to router pools

• selecting a healthy router endpoint inside the chosen pool

• translating the public API request into router-node request shape

• translating router-node responses into stable Portal API responses

• writing usage events and request logs

• returning consistent errors

This is what makes Portal a product, not just a glue layer.

---

6. Core Request and Data Flows

6.1 Hosted Inference Request Flow

Recommended public endpoint:

POST /v1/chat/completions

Example public request shape:

{
  "model": "oss-20b",
  "messages": [
    {
      "role": "user",
      "content": "Explain Cortensor Portal V1."
    }
  ]
}

Detailed flow:

1. Gateway receives request.

2. Gateway generates request_id.

3. Gateway extracts API key from Authorization: Bearer ....

4. Gateway verifies key with Unkey.

5. Gateway loads cached key metadata or looks up api_keys using unkey_key_id.

6. Gateway confirms organization and key are active.

7. Gateway validates request shape.

8. Gateway reads model from request body.

9. Gateway resolves model_catalog.model_alias.

10. Gateway checks plan entitlements and model_access_policies.

11. Gateway applies rate limit through Unkey or fast-state layer.

12. Gateway checks quota policy for the organization / key.

13. Gateway resolves model_alias to router_pools.default_router_pool_id.

14. Gateway selects a healthy router_pool_nodes row.

15. Gateway transforms the public request into router-node request shape.

16. Gateway calls the selected Cortensor router node.

17. Gateway normalizes the router response.

18. Gateway writes usage_events and request_logs.

19. Gateway updates async rollups if needed.

20. Gateway returns normalized response to customer.

---

6.2 API Key Create Flow

1. Authenticated user opens create-key flow from Portal UI.

2. Portal backend verifies:

   • user identity

   • organization membership / ownership context

   • plan allowance (e.g. max active keys)

3. Portal backend requests key creation through Unkey.

4. Unkey returns key material / identifier.

5. Portal backend writes durable metadata into api_keys.

6. Raw secret is shown once to the user.

7. Audit event is recorded.

Key point:

• Portal owns metadata and ownership semantics.

• Unkey supports issuance and hot-path verification.

---

6.3 API Key Revoke Flow

1. Authenticated user requests revoke action.

2. Portal backend verifies key ownership and account/org authorization.

3. Portal backend calls Unkey revoke / disable.

4. Portal backend updates api_keys.status, revoked_at, and revoked_by_user_id.

5. Audit event is recorded.

6. UI updates immediately.

---

6.4 Usage Writeback Flow

After a request completes:

1. Gateway has:

   • request_id

   • key/org/model context

   • router pool and router node identifiers

   • request outcome

2. Gateway writes:

   • request_logs

   • usage_events

3. If needed, async processes later update:

   • usage_rollups

   • billing_ledger

   • derived dashboard summaries

4. Request tracing remains possible via request_id.

The durable write path should remain Portal-owned even if some writes happen asynchronously.

---

6.5 Reconciliation Flow (Later-Ready)

Portal should eventually be able to reason about differences between:

• request accepted by gateway

• request forwarded to backend

• inference completed by router

• usage written durably

V1 does not need perfect reconciliation, but the backend should preserve enough information to reconcile later using:

• request_id

• request_logs

• usage_events

• router target metadata

• status and latency fields

---

7. Recommended Supabase Tables

The exact schema can evolve, but V1 should start with the following durable tables.

7.1 portal_users

Stores Portal-side user profile data linked to auth.

Suggested fields:

id uuid primary key
auth_user_id text unique not null
email text not null
display_name text
first_name text
last_name text
avatar_url text
created_at timestamptz not null
updated_at timestamptz not null
last_seen_at timestamptz
status text not null default 'active'

Notes:

• auth_user_id is the bridge to the chosen auth provider.

• Keep user profile fields here if Portal needs product-side profile data.

• Do not store secrets here.

---

7.2 organizations

Stores account/team ownership.

Suggested fields:

id uuid primary key
name text not null
slug text unique
primary_owner_user_id uuid references portal_users(id)
plan_id uuid references plans(id)
status text not null default 'active'
created_at timestamptz not null
updated_at timestamptz not null

Notes:

• Even if V1 starts mostly single-user, keep the org/account concept early.

• API keys should generally belong to an organization or account context, not only a raw user record.

---

7.3 organization_members

Maps users to organizations.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
user_id uuid references portal_users(id)
role text not null
created_at timestamptz not null
updated_at timestamptz not null
unique(organization_id, user_id)

Suggested roles:

owner
admin
developer
viewer

---

7.4 api_keys

Stores Portal metadata for Unkey-backed API keys.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
created_by_user_id uuid references portal_users(id)
unkey_key_id text unique not null
name text not null
prefix text
masked_key text
status text not null default 'active'
last_used_at timestamptz
expires_at timestamptz
created_at timestamptz not null
revoked_at timestamptz
revoked_by_user_id uuid references portal_users(id)
metadata jsonb not null default '{}'

Notes:

• Store only metadata, never the full API key secret.

• unkey_key_id links Portal metadata to Unkey.

• masked_key is safe for UI display.

• status should reflect Portal product state.

---

7.5 plans

Defines product plans.

Suggested fields:

id uuid primary key
code text unique not null
name text not null
description text
status text not null default 'active'
created_at timestamptz not null
updated_at timestamptz not null

Example plan codes:

free
pro
internal
enterprise

---

7.6 plan_entitlements

Defines what each plan allows.

Suggested fields:

id uuid primary key
plan_id uuid references plans(id)
entitlement_key text not null
entitlement_value jsonb not null
created_at timestamptz not null
updated_at timestamptz not null
unique(plan_id, entitlement_key)

Example entitlement keys:

allowed_models
session_request_limit
weekly_request_limit
monthly_request_limit
max_api_keys
rate_limit_rpm
rate_limit_burst

Example value:

{
  "models": ["oss-20b", "qwen"]
}

---

7.7 model_catalog

Defines product-facing model aliases.

Suggested fields:

id uuid primary key
model_alias text unique not null
display_name text not null
family text not null
description text
status text not null default 'active'
default_router_pool_id uuid references router_pools(id)
created_at timestamptz not null
updated_at timestamptz not null
metadata jsonb not null default '{}'

Example aliases:

oss-20b
oss-120b
gemma-4
qwen

Notes:

• This is what the public API should expose.

• Do not expose router hostnames or session IDs as model names.

---

7.8 model_access_policies

Optional override table for per-org model access.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
model_id uuid references model_catalog(id)
access text not null
created_at timestamptz not null
updated_at timestamptz not null
unique(organization_id, model_id)

Suggested access values:

allow
deny
preview

Notes:

• Use this for beta access, allowlists, or emergency model disablement.

• Plan entitlements define defaults. This table defines overrides.

---

7.9 quota_windows

Stores durable quota policy windows.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
api_key_id uuid references api_keys(id)
window_type text not null
window_start timestamptz not null
window_end timestamptz not null
limit_count integer not null
used_count integer not null default 0
created_at timestamptz not null
updated_at timestamptz not null
unique(organization_id, api_key_id, window_type, window_start)

Example window_type values:

session
daily
weekly
monthly

Notes:

• For V1, this can support durable visibility and reconciliation.

• For hot-path enforcement, prefer Unkey / fast-state counters, then write durable events/rollups.

---

7.10 usage_events

Append-only usage ledger for metering and billing.

Suggested fields:

id uuid primary key
request_id text unique not null
organization_id uuid references organizations(id)
api_key_id uuid references api_keys(id)
model_id uuid references model_catalog(id)
router_pool_id uuid references router_pools(id)
status text not null
input_tokens integer
output_tokens integer
total_tokens integer
request_count integer not null default 1
latency_ms integer
cost_units numeric
created_at timestamptz not null
metadata jsonb not null default '{}'

Notes:

• This should be append-only where possible.

• Use request_id for idempotency and tracing.

• Token fields can remain nullable until backend usage reporting is reliable.

---

7.11 usage_rollups

Precomputed usage for dashboard speed.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
api_key_id uuid references api_keys(id)
model_id uuid references model_catalog(id)
period_type text not null
period_start timestamptz not null
period_end timestamptz not null
request_count integer not null default 0
input_tokens integer not null default 0
output_tokens integer not null default 0
total_tokens integer not null default 0
cost_units numeric not null default 0
updated_at timestamptz not null
unique(organization_id, api_key_id, model_id, period_type, period_start)

Example period_type values:

hour
day
week
month

---

7.12 billing_ledger

Durable billing/accounting events.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
event_type text not null
amount numeric
currency text
status text not null
provider text
provider_reference text
created_at timestamptz not null
metadata jsonb not null default '{}'

Example event types:

credit_grant
usage_debit
payment_received
invoice_created
adjustment
refund

---

7.13 router_pools

Internal metadata for managed router pools.

Suggested fields:

id uuid primary key
name text not null
pool_key text unique not null
model_family text not null
status text not null default 'active'
selection_strategy text not null default 'round_robin'
created_at timestamptz not null
updated_at timestamptz not null
metadata jsonb not null default '{}'

Example pool keys:

oss-20b-primary
oss-120b-primary
gemma-4-primary
qwen-primary

---

7.14 router_pool_nodes

Stores actual managed router endpoints.

Suggested fields:

id uuid primary key
router_pool_id uuid references router_pools(id)
name text not null
base_url text not null
status text not null default 'active'
weight integer not null default 100
health_status text
last_health_check_at timestamptz
created_at timestamptz not null
updated_at timestamptz not null
metadata jsonb not null default '{}'

Notes:

• base_url is internal and must never be exposed to customer UI/API responses.

• Status can support:

  • active

  • draining

  • disabled

  • maintenance

---

7.15 request_logs

Operational request log.

Suggested fields:

id uuid primary key
request_id text unique not null
organization_id uuid references organizations(id)
api_key_id uuid references api_keys(id)
model_alias text
router_pool_id uuid references router_pools(id)
router_node_id uuid references router_pool_nodes(id)
status_code integer
error_code text
latency_ms integer
created_at timestamptz not null
metadata jsonb not null default '{}'

Notes:

• Do not store full prompts/responses by default.

• If request/response capture is ever needed later, make it explicit, opt-in, and retention-controlled.

---

7.16 audit_events

Admin and user action trail.

Suggested fields:

id uuid primary key
organization_id uuid references organizations(id)
actor_user_id uuid references portal_users(id)
event_type text not null
target_type text
target_id text
created_at timestamptz not null
metadata jsonb not null default '{}'

Example event types:

api_key.created
api_key.revoked
plan.changed
model_access.updated
router_pool.drained

---

8. Gateway Logic Checklist

Before calling a router node, the API gateway should check:

• API key exists and is valid through Unkey

• Portal-side key metadata exists

• key status is active

• organization status is active

• requested model exists

• requested model is active

• organization plan allows the model

• organization override policy does not deny the model

• request is within rate limit

• request is within quota

• router pool exists and is active

• router node exists and is healthy

After router-node response, the gateway should:

• normalize success response

• normalize error response

• record usage event

• record request log

• update last-used timestamp for the API key

• emit metrics/traces

---

9. Router Node Call Boundary

The gateway should call actual Cortensor router nodes only after product checks pass.

Customer-facing request:

POST /v1/chat/completions
model = "oss-20b"

Internal resolution:

"oss-20b"
  -> model_catalog row
  -> router_pools.default_router_pool_id
  -> router_pool_nodes healthy endpoint
  -> actual router node HTTP request

The customer should not know:

• which router node served the request

• which session served the request

• how many nodes are in the pool

• whether a pool is draining or failing over

---

10. Error Shape

Use stable product errors from the gateway.

Suggested error response:

{
  "error": {
    "code": "model_not_allowed",
    "message": "This API key is not allowed to use the requested model.",
    "request_id": "req_..."
  }
}

Suggested codes:

invalid_api_key
revoked_api_key
rate_limited
quota_exceeded
model_required
model_not_found
model_not_allowed
router_pool_unavailable
router_request_failed
internal_error

The error surface should remain Portal-owned and productized, not router-native.

---

11. Hot Path vs Durable Path

Keep the request hot path lean.

Hot Path should prefer

• Unkey key verification

• Unkey or fast-state rate limit

• cached key / org / model / plan metadata

• router pool health cache

Durable Path should write

• usage events

• request logs

• billing ledger events

• rollups

• audit events

If a durable write fails after a successful router response, the gateway should not necessarily fail the customer request. Prefer queue/retry for usage and billing writes once V1 matures.

---

12. Admin Controls to Plan For

V1 admin/internal tools should eventually support:

• disable API key

• disable organization

• allow / deny model for organization

• disable model globally

• drain router pool

• disable router node

• inspect request logs

• inspect usage events

• grant credits or adjust billing ledger

Not all of these need polished UI on day one, but the backend and data model should be shaped to support them.

---

13. Implementation Order

Recommended backend build order:

1. Create Supabase schema for users, organizations, API keys, plans, model catalog, router pools, usage events, and request logs.

2. Seed free plan, initial model aliases, and initial router pools.

3. Implement auth sign-in and user/org bootstrap.

4. Implement API key create/revoke flow with Unkey and api_keys metadata.

5. Implement read-only usage dashboard from usage_rollups or mocked rollups.

6. Implement gateway endpoint with Unkey verification.

7. Add model alias resolution and entitlement checks.

8. Add router pool selection and router-node forwarding.

9. Add usage event and request log writes.

10. Add quota/rate-limit visibility and error messaging.

This sequencing keeps the Portal backend grounded in a working product flow rather than abstract platform work.

---

14. V1 Non-Goals

Avoid in V1 unless required:

• exposing raw router-node URLs to customers

• customer-managed sessions

• complex billing dimensions

• full Kubernetes/router autoscaling control plane

• prompt/response retention by default

• router topology display in customer UI

The first version should be a productized hosted API, not an infrastructure console.

---

15. Working Summary

Portal V1 backend should be treated as the owned product control plane for Cortensor Portal.

It exists to coordinate:

• auth identity

• key verification

• durable product/account state

• model entitlement

• quota logic

• router-pool routing

• request normalization

• durable usage writes

In one sentence:

The Portal backend and gateway are the product boundary that transform Portal-issued keys and product-level model names into stable, metered requests against managed Cortensor router pools.