Auth Integration Guide

End-to-end authentication flow with Rise SDK

This guide walks you through implementing authentication with Rise using the official SDK. The Rise SDK handles all the complexity of SIWE and JWT authentication automatically.

Authentication Flow

1. Install SDK

   Install the Rise SDK package

2. Configure Authentication

   Set up SDK with Rise ID and private key or JWT token

3. Automatic Authentication

   SDK handles SIWE signing and JWT token management

4. API Access

   Execute API calls with automatic authentication

SDK Installation

First, install the Rise SDK:

npm install @riseworks/sdk

Complete Integration Example

const { RiseApiClient } = require('@riseworks/sdk');
require('dotenv').config();

// Initialize with Rise ID and private key (recommended)
const client = new RiseApiClient({
  environment: 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.PRIVATE_KEY
  }
});

// Alternative: Initialize with JWT token
const jwtClient = new RiseApiClient({
  environment: 'prod',
  jwtToken: process.env.JWT_TOKEN
});

async function main() {
  try {
    // SDK automatically handles authentication
    console.log('Authenticating with Rise...');
    
    // Get user information
    const user = await client.me.get();
    console.log('Authenticated as:', user.data.name);
    
    // Get user's teams
    const teams = await client.me.teams();
    console.log('Teams:', teams.data);
    
    // Get company information
    const company = await client.company.get();
    console.log('Company:', company.data.name);
    
  } catch (error) {
    console.error('Authentication error:', error.message);
  }
}

// Run the example
if (require.main === module) {
  main();
}

Authentication Methods

Method 1: Rise ID Authentication (Recommended)

Use your Rise ID and wallet private key for automatic authentication:

const { RiseApiClient } = require('@riseworks/sdk');

const client = new RiseApiClient({
  environment: 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.PRIVATE_KEY
  }
});

// SDK automatically handles SIWE and JWT token generation
const user = await client.me.get();

Benefits:

• Automatic JWT generation - SDK handles SIWE signing and JWT token creation
• Token renewal - SDK automatically refreshes expired tokens
• Full API access - Access to all API endpoints including sensitive operations
• Simplified integration - No manual authentication code required

Method 2: JWT Authentication

Use a pre-generated JWT token for direct API access:

const { RiseApiClient } = require('@riseworks/sdk');

const client = new RiseApiClient({
  environment: 'prod',
  jwtToken: process.env.JWT_TOKEN
});

// SDK automatically includes JWT in all requests
const user = await client.me.get();

Use cases:

• Existing JWT tokens - When you already have a valid JWT token
• Read-only operations - For applications that only need to read data
• Simple integrations - When you don’t need sensitive write operations

Error Handling

The SDK provides comprehensive error handling with descriptive error messages:

try {
  const user = await client.me.get();
  console.log('Success:', user.data);
} catch (error) {
  console.error('Authentication error:', error.message);
  
  // Handle specific error types based on message content
  if (error.message.includes('Failed to generate JWT token')) {
    console.error('JWT generation failed. Check your Rise ID and private key.');
  } else if (error.message.includes('401')) {
    console.error('Authentication failed. The SDK will automatically retry.');
  } else if (error.message.includes('403')) {
    console.error('Insufficient permissions for this operation.');
  } else {
    console.error('API Error:', error.message);
  }
}

Common authentication errors:

Error Message	Description	Solution
Failed to generate JWT token	JWT generation failed	Check Rise ID and private key
Rise ID and private key are required	Missing credentials	Provide both Rise ID and private key
Invalid Rise ID address	Rise ID format is invalid	Verify Rise ID format (0x + 40 hex chars)
Private key should be a valid hex string	Private key format is invalid	Check private key format (0x + 64 hex chars)
HTTP 401	Authentication failed	SDK automatically handles JWT refresh
HTTP 403	Insufficient permissions	Check user roles and permissions

Security Best Practices

Never expose private keys in client-side code or commit them to version control.

Secondary Wallets

// Use secondary wallets for API operations
// Never use wallets with significant funds for API authentication
const client = new RiseApiClient({
  environment: 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.SECONDARY_WALLET_PRIVATE_KEY // Use secondary wallet
  }
});

Error Logging

// Log authentication events for security auditing
client.on('auth', (event) => {
  console.log('Authentication event:', event.type, event.timestamp);
});

Troubleshooting

Common Issues

1. “Authentication failed”

   • Verify Rise ID and private key are correct
   • Ensure wallet has sufficient funds for gas fees
   • Check network connectivity

2. “JWT token expired”

   • SDK automatically handles token renewal
   • If issues persist, reinitialize the client

3. “Insufficient permissions”

   • Check user roles and permissions
   • Verify team membership for team-specific operations

4. “Network error”

   • Check internet connection
   • Verify API endpoint is accessible
   • Check firewall settings

Next Steps

Payment Integration

Learn how to process payments with automatic authentication

Team Management

Manage teams and permissions with the SDK

Webhooks

Set up real-time notifications for your integration

Error Handling

Comprehensive error handling and troubleshooting

Need help? See the Authentication page for detailed documentation or contact support at [e-mail]