ZERO-TRUST IDENTITY

Sovereign Authentication

HeadyKey is the zero-trust identity layer for the entire Heady ecosystem. JWT sessions, OAuth2 OIDC, RBAC, API key management, Ed25519 trust receipts, and persistent user storage — all φ-scaled.

Sign In → API Reference
25+
OAuth Providers
4
RBAC Roles
Ed25519
Trust Receipts
φ-scaled
Session TTLs
🔐

JWT Access + Refresh Tokens

HS256-signed access tokens with 1-hour expiry. 30-day refresh tokens with 34-byte (fib(9)) entropy. Session cookies httpOnly + Secure + SameSite=Strict.

👥

Role-Based Access Control

Four-tier RBAC: admin(4), operator(3), user(2), guest(1). Role enforcement middleware checks minimum level on every protected route.

🗝️

API Key Management

Generate hdy_ prefixed keys with SHA-256 hashing. Keys are shown once at creation. Revoke, list, and audit through the management API.

🛡️

Zero-Trust CORS

23 explicit Heady origins whitelisted. Zero wildcard Access-Control-Allow-Origin. Server-to-server calls (no Origin header) allowed.

🧠

Persistent User Memory

Onboarding preferences stored in 384D pgvector memory (user_memory_t2). Buddy configuration, interests, and plan persisted across sessions.

📋

5-Stage Onboarding

Identity → Interests → Buddy Config → Plan Selection → Completion. Auto-generates API key. Stores preferences in persistent memory tier.

Authentication Flow

1

Sign In

Email/password or OAuth provider

2

Verify

JWT issued + session cookie set

3

Onboard

5-stage personalization flow

4

API Key

hdy_ key auto-generated

5

Access

Full ecosystem access

OAuth Providers

GoogleGitHubMicrosoft AppleDiscordSlack HuggingFaceGitLabLinkedIn Twitter/XFacebookNotion AtlassianOktaAuth0 SalesforceZoomSpotify RedditTwitchFigma ShopifyStripe ConnectOneLogin Bitbucket

API Endpoints

Base URL: https://headykey.com/api
POST/api/auth/registerCreate account
POST/api/auth/loginAuthenticate → JWT + refresh
POST/api/auth/refreshRefresh access token
POST/api/auth/logoutClear session
GET/api/auth/meCurrent user profile
GET/api/auth/verifyVerify JWT or API key
POST/api/auth/api-keysGenerate hdy_ API key
GET/api/auth/api-keysList your API keys
DEL/api/auth/api-keys/:idRevoke API key
POST/api/session/startWidget session creation
POST/api/provider/startOAuth provider redirect
POST/onboarding/completeSave onboarding data
GET/onboarding/statusCheck onboarding progress
// Example: Generate API Key curl -X POST https://headykey.com/api/auth/api-keys \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{"description": "My production key"}' // Response: { "id": "abc123", "key": "hdy_8f3a9b2c...", "prefix": "hdy_8f3a9b2c", "role": "user", "warning": "Store this key securely. It cannot be retrieved again." }

Token Lifecycle

Access Token

JWT, HS256 signed, 1-hour expiry. Contains userId, email, role. Passed via Authorization: Bearer header.

Refresh Token

34-byte (fib(9)) CSPRNG hex. 30-day TTL. Hash-indexed in PostgreSQL. Exchange for new access token.

Session Cookie

__heady_session. 8-hour TTL (fib(6) hours). httpOnly, Secure, SameSite=Strict. LIFO cleanup on logout.

API Key

hdy_ prefix. SHA-256 hashed in database. Optional TTL. Validated via X-API-Key header. Timing-safe comparison.

Heady Ecosystem

HeadyMe HeadySystems HeadyAI HeadyBuddy HeadyConnection HeadyBot HeadyAPI HeadyIO HeadyMCP HeadyOS HeadyVault