Backup API Authentication

The Sigma Auth backup service provides secure storage and retrieval of encrypted Bitcoin key backups.

Authentication

Use the JWT access token from the OAuth flow:

Authorization: Bearer <access_token>

Endpoint Authentication Requirements

Authenticated Endpoints

These endpoints require authentication to protect user data:

Endpoint	Method	Authentication	Description
`/backup`	GET	Bearer token	Retrieve your encrypted backup
`/backup`	POST	Bearer token	Store encrypted backup
`/backup/status`	GET	Bearer token	Check backup status
`/backup/link-oauth`	POST	Bearer token	Link OAuth account to Bitcoin identity
`/backup/oauth-accounts`	GET	Bearer token	List linked OAuth accounts

Public Endpoints

These endpoints are intentionally public to enable cross-device restore:

Endpoint	Method	Authentication	Description
`/backup/oauth`	GET	None (OAuth ID required)	Retrieve backup by OAuth account

Authentication Examples

Example Request

// After OAuth authentication
const response = await fetch('https://auth.sigmaidentity.com/backup/status', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Security Design

Why OAuth Backup Retrieval is Public

The /backup/oauth endpoint doesn't require authentication because:

Enables cross-device restore - Users can restore from a new device without their Bitcoin key
OAuth provider verification - The OAuth provider already verified the user's identity
Client-side encryption - Backups are encrypted and require a password to decrypt
No sensitive data exposed - Only encrypted blobs are returned

Protection Mechanisms

Even though OAuth backup retrieval is public, it's secure because:

Strong encryption: AES-256-GCM encryption with user-chosen passwords
OAuth verification: Must prove ownership of the OAuth account
Rate limiting: Prevents brute force attempts
No key exposure: Private keys are never transmitted or stored in plaintext

Best Practices

For Storing Backups

import { encryptBackup, type WifBackup } from 'bitcoin-backup';

// 1. Authenticate user
const accessToken = await authenticateUser();

// 2. Create backup object and encrypt client-side
const backup: WifBackup = {
  wif: privateKey.toWif(),
  label: 'My Wallet',
  createdAt: new Date().toISOString()
};
const encryptedBackup = await encryptBackup(backup, password);

// 3. Store encrypted backup
await fetch('https://auth.sigmaidentity.com/backup', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    data: encryptedBackup,
    format: 'WifBackup', // Helps server categorize the backup type
    version: 1,
    metadata: {
      source: 'web',
      clientVersion: '1.0.0'
    }
  })
});

For Retrieving Backups

// Authenticated retrieval (when user has their key)
const backup = await fetch('https://auth.sigmaidentity.com/backup', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

// OAuth-based retrieval (for cross-device restore)
const oauthBackup = await fetch(
  'https://auth.sigmaidentity.com/backup/oauth?oauthId=google|123456789'
);

Error Responses

Authentication Failures

{
  "error": "unauthorized",
  "error_description": "Invalid or expired authentication token"
}

Missing Authentication

{
  "error": "authentication_required",
  "error_description": "This endpoint requires authentication"
}

Rate Limiting

All backup endpoints are rate-limited to prevent abuse:

Authenticated requests: 100 requests per minute
OAuth backup retrieval: 10 requests per minute per IP
Failed authentication: Progressive delays after failed attempts

Backup Overview - How the backup system works
OAuth Restore - Cross-device restore guide
Security Details - Encryption and security implementation
API Endpoints - Complete endpoint reference

On this page