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. For Next.js apps, the @sigma-auth/better-auth-plugin wraps this flow (PKCE, state, token exchange) — use it instead of hand-rolling the OAuth calls.

• Authorization URL: https://auth.sigmaidentity.com/oauth2/authorize
• Token URL: https://auth.sigmaidentity.com/api/auth/oauth2/token
• UserInfo URL: https://auth.sigmaidentity.com/api/auth/oauth2/userinfo
• OpenID Discovery: https://auth.sigmaidentity.com/.well-known/openid-configuration

The /userinfo endpoint returns standard OIDC claims plus custom fields:

• sub: User ID
• name: Display name (from BAP profile's alternateName)
• given_name, family_name: Names from BAP identity
• picture: Profile image URL
• pubkey: Bitcoin public key (unique identifier)
• bap: Full BAP profile object (if user has on-chain identity)

Note: The bap field contains the complete profile from api.sigmaidentity.com, including idKey, rootAddress, addresses, and identity data.

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 OAuth 2.1 access tokens. User information is retrieved via the /userinfo endpoint:

{
  "sub": "user_abc123def456",
  "name": "JohnDoe",
  "given_name": "John",
  "family_name": "Doe",
  "picture": "https://ordfs.network/abc123_62",
  "pubkey": "02a94e09bcd6085e580f9214d2814e985f348b1b24121b2aff70a169f971ff5699",
  "bap": {
    "idKey": "A4PYmuKGG61WCjjBaRpuSEbqytG",
    "rootAddress": "1GXdTRDtQGKZ6yp2oUkDf8SuVhBf8Ww7ki",
    "identity": {
      "@type": "Person",
      "alternateName": "JohnDoe",
      "givenName": "John",
      "familyName": "Doe"
    }
  }
}

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

Getting Help

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