> ## Documentation Index
> Fetch the complete documentation index at: https://docs.riseworks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Configuration

> Configure the Rise SDK for your environment and use case

<Note>
  Proper SDK configuration is essential for secure and efficient API integration.
</Note>

## 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:

```typescript theme={null}
import { RiseApiClient } from '@riseworks/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

```typescript theme={null}
// 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

```typescript theme={null}
// 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)

```typescript theme={null}
// 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.

```typescript theme={null}
import { WebhookValidator } from '@riseworks/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.

```typescript theme={null}
import { WebhookValidator } from '@riseworks/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.

```typescript theme={null}
// 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

<CardGroup cols={2}>
  <Card title="Skills" icon="sparkles" href="/sdk/skills/ai-coding-skills">
    Copy Claude-style skills from `@riseworks/riseworks-sdk` into `.claude/skills/`.
  </Card>

  <Card title="Authentication Guide" icon="shield" href="/authentication">
    Learn about JWT and SIWE authentication methods and how to implement them in your application.
  </Card>

  <Card title="Webhooks Guide" icon="webhook" href="/webhooks">
    Set up webhook endpoints, implement validation, and handle real-time events from Rise.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Explore all available API endpoints, request/response formats, and integration examples.
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Learn how to handle errors, implement retry logic, and debug common integration issues.
  </Card>
</CardGroup>