Skip to main content
Proper SDK configuration is essential for secure and efficient API integration.

​
Configuration Options

The Rise SDK provides flexible configuration options to adapt to your specific needs. You can configure authentication methods, network settings, and environment-specific behavior.

​
Core Configuration Parameters

The SDK supports the following configuration options: 
import { RiseApiClient } from '@riseworks/sdk';

const client = new RiseApiClient({
  environment: 'prod',           // 'dev' | 'stg' | 'prod' (default: 'prod')
  baseUrl: 'https://custom-api.com', // Custom base URL (overrides environment)
  jwtToken: 'your-jwt-token',    // JWT authentication
  riseIdAuth: {                  // SIWE authentication
    riseId: '0x...',
    privateKey: '0x...'
  },
  timeout: 30000                 // Request timeout in ms (default: 30000)
});

​
Configuration Priority

The SDK follows a specific priority order for configuration:
  1. Custom baseUrl (if provided, overrides environment)
  2. Environment setting (determines API endpoint)
  3. Authentication method (JWT token or SIWE credentials)
  4. Network settings (timeout, headers)

​
Authentication Configuration

The Rise SDK supports two authentication methods, each with different use cases and security implications.

​
JWT Authentication

JWT (JSON Web Token) authentication is the simplest method for API access. Use this when you already have a valid JWT token from your authentication system. Best for: Quick integration, existing JWT tokens, read-only operations 
// Simple JWT configuration
const client = new RiseApiClient({
  environment: 'prod',
  jwtToken: process.env.JWT_TOKEN
});
Note: JWT tokens are obtained through SIWE authentication or your existing authentication system.

​
SIWE Authentication

SIWE (Sign-In with Ethereum) authentication provides the most comprehensive access. The SDK automatically handles JWT token generation and renewal. Best for: Full API access, sensitive operations, automatic token management 
// SIWE with Rise ID and private key
const client = new RiseApiClient({
  environment: 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.PRIVATE_KEY
  }
});
Security Note: Always use environment variables for sensitive credentials and consider using secondary wallets for API operations.

​
Network Configuration

Network configuration allows you to customize how the SDK communicates with the Rise API, including timeout settings and custom headers.

​
Request Timeout

The timeout setting controls how long the SDK waits for API responses before considering the request failed. This is crucial for handling slow network connections or API delays. Default: 30 seconds (30000ms) 
// Custom timeout (default: 30 seconds)
const client = new RiseApiClient({
  environment: 'prod',
  jwtToken: process.env.JWT_TOKEN,
  timeout: 60000  // 60 seconds
});
When to adjust timeout:
  • Increase timeout: Slow network connections, large data transfers
  • Decrease timeout: Real-time applications, fail-fast scenarios

​
Webhook Validator Configuration

The Rise SDK includes a built-in webhook validator that ensures the security and authenticity of incoming webhook events. This is essential for protecting your application from malicious requests.

​
Basic Webhook Validator Setup

The webhook validator uses HMAC-SHA256 signatures to verify that webhooks are genuinely from Rise. This prevents replay attacks and ensures data integrity. 
import { WebhookValidator } from '@riseworks/sdk';

// Initialize with webhook secret
const validator = new WebhookValidator(process.env.WEBHOOK_SECRET);

// Express.js webhook endpoint
app.post('/webhooks/rise', (req, res) => {
  try {
    // Validate webhook signature
    const event = validator.validateEvent(
      req.body,
      req.headers['rise-signature']
    );
    
    console.log('Valid webhook received:', event.event_type);
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook validation failed:', error.message);
    res.status(400).json({ error: 'Invalid signature' });
  }
});
Security Features:
  • HMAC-SHA256 signatures for cryptographic verification
  • Timestamp validation to prevent replay attacks
  • Automatic signature parsing from Rise headers

​
Advanced Webhook Validator Configuration

For production applications, you may want more control over webhook validation behavior. The SDK provides advanced configuration options for custom tolerance settings and non-throwing validation. 
import { WebhookValidator } from '@riseworks/sdk';

// Initialize with custom tolerance (default: 600 seconds = 10 minutes)
const validator = new WebhookValidator(process.env.WEBHOOK_SECRET, {
  tolerance: 300 // 5 minutes tolerance
});

// Safe validation (non-throwing)
app.post('/webhooks/rise', (req, res) => {
  const result = validator.validateEventSafe(
    req.body,
    req.headers['rise-signature']
  );
  
  if (result.isValid && result.event) {
    console.log('Valid event:', result.event.event_type);
    // Process event
    res.status(200).json({ received: true });
  } else {
    console.error('Validation failed:', result.error);
    res.status(400).json({ error: result.error });
  }
});
Advanced Features:
  • Custom tolerance: Adjust time window for timestamp validation
  • Safe validation: Non-throwing validation with detailed error information
  • Event typing: TypeScript support for webhook events

​
Webhook Signature Generation

The SDK provides signature generation capabilities for testing and custom validation scenarios. This is useful for creating test webhooks or implementing custom validation logic. 
// Generate signature for testing
const timestamp = Math.floor(Date.now() / 1000);
const payload = JSON.stringify({ test: 'data' });
const signature = validator.generateSignature(timestamp, payload);

console.log('Generated signature:', signature);
Use Cases:
  • Testing: Generate valid signatures for webhook testing
  • Custom validation: Implement custom validation logic
  • Debugging: Verify signature generation matches Rise’s format

​
Next Steps

Authentication Guide

Learn about JWT and SIWE authentication methods and how to implement them in your application.

Webhooks Guide

Set up webhook endpoints, implement validation, and handle real-time events from Rise.

API Reference

Explore all available API endpoints, request/response formats, and integration examples.

Error Handling

Learn how to handle errors, implement retry logic, and debug common integration issues.
⌘I