Auth Integration Guide

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

Install SDK

Install the Rise SDK package

Configure Authentication

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

Automatic Authentication

SDK handles SIWE signing and JWT token management

API Access

Execute API calls with automatic authentication

SDK Installation

First, install the Rise SDK:

npm install @riseworks/riseworks-sdk
# Or: yarn add @riseworks/riseworks-sdk
# Or: pnpm add @riseworks/riseworks-sdk

Complete Integration Example

const { RiseApiClient } = require('@riseworks/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/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/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

“Authentication failed”
- Verify Rise ID and private key are correct
- Ensure wallet has sufficient funds for gas fees
- Check network connectivity
“JWT token expired”
- SDK automatically handles token renewal
- If issues persist, reinitialize the client
“Insufficient permissions”
- Check user roles and permissions
- Verify team membership for team-specific operations
“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

Getting Started

Advanced

Authentication Flow

SDK Installation

Complete Integration Example

Authentication Methods

Method 1: Rise ID Authentication (Recommended)

Method 2: JWT Authentication

Error Handling

Security Best Practices

Secondary Wallets

Error Logging

Troubleshooting

Common Issues

Next Steps

Payment Integration

Team Management

Webhooks

Error Handling

​Authentication Flow

​SDK Installation

​Complete Integration Example

​Authentication Methods

​Method 1: Rise ID Authentication (Recommended)

​Method 2: JWT Authentication

​Error Handling

​Security Best Practices

​Secondary Wallets

​Error Logging

​Troubleshooting

​Common Issues

​Next Steps

Payment Integration

Team Management

Webhooks

Error Handling

Authentication Flow

SDK Installation

Complete Integration Example

Authentication Methods

Method 1: Rise ID Authentication (Recommended)

Method 2: JWT Authentication

Error Handling

Security Best Practices

Secondary Wallets

Error Logging

Troubleshooting

Common Issues

Next Steps