Skip to main content

Introduction

Welcome to the SVA OAuth Integration Documentation! This comprehensive guide will help you integrate SVA (Secure Vault Authentication) OAuth 2.0 into your applications.

What is SVA OAuth?​

SVA OAuth is a secure, privacy-first OAuth 2.0 provider that enables applications to authenticate users and access their identity data through a zero-knowledge architecture. Unlike traditional OAuth providers, SVA delivers user identity claims directly in a cryptographically signed JWT, eliminating the need for inefficient API calls to a /userinfo endpoint.

Key Features​

🔐 Secure by Default​

  • PKCE Support: Built-in Proof Key for Code Exchange for enhanced security
  • State Parameter: CSRF protection on every OAuth flow
  • Signed Data Tokens: Cryptographically signed JWTs ensure data integrity
  • Zero-Knowledge Architecture: User data remains encrypted until decrypted client-side

⚡ High Performance​

  • Stateless Design: No /userinfo endpoint calls needed
  • Direct Token Claims: Identity data delivered in the token response
  • Automatic Token Refresh: Seamless token management with middleware
  • Minimal Network Overhead: Zero additional API calls after token exchange

🛠️ Developer Friendly​

  • Simple Integration: Get started in 5 minutes
  • Django Package: sva-oauth-client for easy Django integration
  • Comprehensive Documentation: Complete guides and examples
  • Type Hints: Full type support for better IDE experience

🎯 Privacy First​

  • User Control: Granular scope approval on consent screen
  • Zero-Knowledge: Provider never sees plaintext user data
  • Client-Side Decryption: Data decrypted only in user's browser
  • Data Attestation: Cryptographic notary for verified claims

How It Works​

SVA OAuth follows the standard OAuth 2.0 Authorization Code Flow with PKCE, but with a unique twist:

  1. Authorization Request: Your app redirects users to SVA's authorization endpoint
  2. User Consent: Users review and approve requested scopes on the consent screen
  3. Data Attestation: SVA issues a cryptographically signed data token containing approved claims
  4. Token Exchange: Your app exchanges the authorization code for tokens (including the data token)
  5. Stateless Access: Decode user data directly from the signed token - no API calls needed!

Architecture Overview​

SVA OAuth consists of three main components:

  • SVA OAuth Provider (sva_oauth): Public-facing OAuth 2.0/OIDC server
  • SVA Core (sva_server): Manages user accounts and zero-knowledge encrypted vaults
  • SVA Client (sva_client): React application providing the consent UI

All components work together to provide a secure, privacy-preserving authentication experience.

What You'll Learn​

This documentation covers:

  • Quick Start: Get up and running in 5 minutes
  • Installation: Step-by-step setup guide
  • API Reference: Complete reference for all components
  • Architecture: Deep dive into how SVA OAuth works
  • Security: Best practices and security considerations
  • Examples: Real-world integration examples
  • Troubleshooting: Common issues and solutions

Next Steps​

Ready to get started? Head over to the Quick Start Guide to integrate SVA OAuth into your application in just a few minutes!

Or explore the Architecture Overview to understand how SVA OAuth works under the hood.