Authentication & Identity
Hybrid authentication and onboarding using wallet signatures and session-based access.
Overview
Spiral uses a hybrid authentication model designed to bridge two worlds:
- Decentralized identity (wallets + blockchain)
- Traditional web experience (sessions, cookies, JWT)
The Solana blockchain acts as the source of truth, while the backend provides performance, ergonomics, and fine-grained access control.
Core Principle
The backend never grants permissions on its own. All identities and organizational memberships must exist on-chain.
Involved Components
User Wallet
Identity proof via cryptographic signatures (SIWS).
API Backend
Invitation validation, on-chain verification, and session issuance.
Solana Blockchain
Source of truth for identity, membership, and permissions.
PostgreSQL
Read-optimized projection layer for on-chain state.
Authentication Flow
The complete authentication and onboarding flow is defined by the diagram below:
Reading the Diagram
This flow illustrates how on-chain confirmation and off-chain control cooperate without compromising blockchain sovereignty.
Step-by-Step Flow
Security Guarantees
Verifiable Identity
No user can authenticate without proving wallet ownership.
Auditable Authorization
Organizational memberships are recorded on-chain.
No Silent Privilege Escalation
The backend cannot grant access independently.
Why Hybrid Authentication?
Architectural Trade-off
Pure on-chain authentication is secure but impractical at scale.
Pure Web2 authentication is fast but fragile.
Spiral explicitly combines both approaches in a verifiable and scalable way.