Cortensor Portal V1 Detailed Spec 02 - Auth / Clerk
Status
Draft
Purpose
This document defines the authentication layer for Cortensor Portal V1.
Portal V1 should assume a Clerk-first auth approach for the initial version. This spec covers:
why Clerk is the preferred V1 auth choice
what auth flows V1 should support
how auth should interact with the Portal web app and backend
what user/account state the auth layer should own
1. Summary
Portal V1 should use Clerk as the primary authentication system.
Clerk should handle:
sign in
sign up
session management
protected routes
user identity basics
auth UI primitives
The Portal backend should treat Clerk as the source of authenticated user identity, while durable product/account state remains in Supabase and Portal-controlled tables.
2. Why Clerk For V1
Clerk fits V1 because it gives:
polished hosted auth UX
fast productization
less auth surface area to build from scratch
easy session handling for a web app
room for multiple login methods later
It is especially aligned with the reviewed UI direction, which expects a clean hosted sign-in experience instead of a low-level or improvised auth flow.
3. V1 Auth Goals
make sign-in feel trustworthy and familiar
reduce implementation time for auth
support protected Portal routes cleanly
provide a stable user identity for API key ownership and usage attribution
keep auth concerns distinct from API key concerns
4. Non-Goals
building a custom auth system
putting product authorization rules inside Clerk
replacing durable Portal account state with Clerk metadata alone
designing a complete org-admin suite in the first pass
5. Recommended V1 Flows
Required flows
sign up
sign in
sign out
session persistence
session expiration handling
passwordless or email-based flow if desired through Clerk
Good V1 additions if simple enough
social sign-in
wallet-aligned sign-in path later if actually needed
email verification
Deferred unless needed
advanced organization switching
enterprise SSO
complex RBAC inside the customer UI
6. Route Protection Model
Protected routes should include:
/portal/portal/usage/portal/keys/portal/billing/portal/docs/portal/profile
Unauthenticated users should be redirected to:
/sign-in
If a session expires:
show a clean re-auth path
avoid dumping the user into a broken partially-rendered shell
7. Identity Model
Clerk should own:
authenticated user identity
auth session lifecycle
login methods and verification
user-level auth metadata
The Portal system should own:
Portal user record
organization membership if used
API key ownership
plan and entitlement state
usage and billing records
Recommended identity mapping
Clerk user ID should map to a Portal
usersrowthat row can then map to organizations, subscriptions, and keys
8. First Sign-In Behavior
On first successful sign-in:
Clerk authenticates the user
Portal backend creates or upserts a Portal user record
default account context is resolved
user is redirected into the Portal shell
if no API keys exist, the app may guide the user to create the first key
This should feel automatic and low-friction.
9. Profile Responsibilities
For V1, Clerk can provide the baseline profile identity:
email
display name
avatar if present
Portal can later extend that profile with:
username
organization context
lightweight custom profile fields
Portal should not depend on expanded profile complexity to ship V1.
10. Backend Auth Responsibilities
The Portal backend should:
verify Clerk session or token on protected requests
resolve authenticated user identity
map authenticated user to Portal account state
reject unauthorized resource access
It should not:
trust raw client-provided user identifiers
rely on frontend-only protection for sensitive operations
11. Auth And API Keys
Auth identity and API key identity are related but separate.
Clerk auth should be used for:
dashboard access
account management actions
key management UI
Portal API keys should be used for:
hosted inference API requests
This separation is important because:
dashboard auth is user/session-based
hosted API traffic is programmatic and key-based
12. Failure States
Important V1 auth states:
unauthenticated
loading auth state
authenticated
expired session
email verification pending if enabled
backend user provisioning failure
The UI should handle each cleanly and avoid exposing implementation jargon.
13. Security Notes
all protected Portal actions should require verified auth context
resource ownership checks must happen server-side
auth must not be confused with API authorization semantics
dashboard identity should not automatically imply universal backend permissions
14. Open Questions
should V1 include only email-based auth initially?
should social providers be enabled from launch?
how much organization support is needed in V1?
does the team want a future wallet-based path visible in the auth surface?
15. Relationship To Other Specs
This spec connects directly to:
Portal V1 Top-Level Reference Spec
01 UI / UX / Web App
03-api-key-management.md05-portal-backend-control-plane.md06-data-model-and-durable-state.md
Last updated