Integration Guide

Sigma Auth provides Bitcoin-based authentication through standard OAuth 2.0/OIDC protocols. This guide covers the core concepts and integration patterns.

Overview

Sigma Auth acts as an OAuth 2.0 identity provider that uses Bitcoin cryptographic signatures instead of passwords. Your application integrates using standard OAuth flows.

Authentication Flow

Integration Approaches

1. OAuth 2.0 Flow (Recommended)

Use standard OAuth 2.0 authorization code flow with your preferred authentication library:

• Authorization URL: https://auth.sigmaidentity.com/authorize?provider=sigma
• Token URL: https://auth.sigmaidentity.com/token
• UserInfo URL: https://auth.sigmaidentity.com/userinfo

Note: If using NextAuth.js, the /api/auth/* endpoints are created in your frontend application, not on the Sigma Auth server. NextAuth.js acts as a bridge between your app and Sigma Auth's OAuth endpoints.

The /userinfo endpoint returns:

• pubkey: Bitcoin public key (unique identifier)
• bapIdKey: BAP identity key (if user has created a profile)
• profile: Full profile object (if user has created a profile)

Note: Users start without profiles. Use the Profile API to create and manage profiles.

2. Direct API Integration

For applications requiring custom authentication flows, use the Bitcoin signature API directly:

// Direct signature verification
import { getAuthToken } from 'bitcoin-auth';

// Create the auth token
const authToken = getAuthToken({
    privateKeyWif: privateKey.toWif(), // Private key in WIF format
    requestPath: '/sigma/authorize'
});

// Send with X-Auth-Token header
const response = await fetch('https://auth.sigmaidentity.com/sigma/authorize', {
    method: 'POST',
    headers: { 
        'X-Auth-Token': authToken,
        'Content-Type': 'application/json' 
    },
    body: JSON.stringify({
        // Optional body data
    })
});

Platform-Specific Guides

Choose your platform for detailed implementation instructions:

Key Concepts

Bitcoin Identity

Users authenticate with Bitcoin private keys instead of passwords. Each user has:

• Public Key: Unique identifier derived from private key
• Signatures: Cryptographic proofs of identity ownership
• BAP Profile: Optional Bitcoin Attestation Protocol identity data

Session Management

Sigma Auth issues standard JWT tokens containing:

{
  "iss": "https://auth.sigmaidentity.com",
  "sub": "did:bitcoin:id:pubkey",
  "pubkey": "user-public-key",
  "profile": {
    "name": "User Name"
  },
  "exp": 1640995200
}

Security Considerations

• Private keys never leave the user's device
• All authentication uses cryptographic signatures
• JWT tokens are short-lived and verifiable
• Support for encrypted backup and restore

Quick Start

1. Configure OAuth Provider in your application
2. Set up redirect URLs to handle the OAuth callback
3. Implement sign-in flow that redirects to Sigma Auth
4. Handle the callback to exchange code for tokens
5. Use JWT tokens to authenticate API requests

Next Steps

• Choose your platform: Select a detailed guide above
• Test integration: Try the live demo
• Explore customization: See OAuth Providers
• Review security: Check Security Best Practices

Coming Soon: BigBlocks Components

Pre-built components and providers for Sigma Auth will be available through BigBlocks:

• React Components: Ready-to-use authentication UI components
• NextAuth Provider: Drop-in provider for Next.js applications
• Hooks & Utilities: React hooks for authentication state
• CLI Installation: Install via shadcn/ui CLI

Until BigBlocks components are released, use the standard OAuth 2.0 integration examples provided in this documentation.

Getting Help

• API Reference: Complete endpoint documentation
• Examples: Platform-specific implementation examples
• Community: Join discussions on GitHub
• Support: Open an issue for technical help