Skip to main content

Documentation Index

Fetch the complete documentation index at: https://v2-docs.riseworks.io/llms.txt

Use this file to discover all available pages before exploring further.

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

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 MessageDescriptionSolution
Failed to generate JWT tokenJWT generation failedCheck Rise ID and private key
Rise ID and private key are requiredMissing credentialsProvide both Rise ID and private key
Invalid Rise ID addressRise ID format is invalidVerify Rise ID format (0x + 40 hex chars)
Private key should be a valid hex stringPrivate key format is invalidCheck private key format (0x + 64 hex chars)
HTTP 401Authentication failedSDK automatically handles JWT refresh
HTTP 403Insufficient permissionsCheck 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 Hello@Riseworks.io