Authentication

Two things have to be in place before your first authenticated call, and the API returns a 403 even with correct code if either is missing:

Rise has to enable your company for B2B API access in the environment you’re calling. Staging and production are enabled separately, so a request for one does not carry to the other.
The wallet you authenticate with has to hold an authorized role (Owner, Payer, or Treasurer) on your RiseID.

Both are walked through in Getting API Access. Set them up there first, then come back here for the handshake itself.

Rise implements a dual authentication system to ensure maximum security for your integrations. JWT tokens provide session management for all API operations, while SIWE (Sign-In with Ethereum) is required to obtain JWT tokens and adds blockchain-based verification for sensitive transactions. The Rise SDK simplifies this process by handling both authentication layers automatically.

SIWE Authentication

Use your wallet and private key for automatic authentication

JWT Authentication

Use a pre-generated JWT token for direct API access

Authentication Layers

Rise’s dual authentication system consists of two complementary layers:

JWT Authentication Layer

Session management: Provides secure session management for all API operations
User identity: Verifies user identity and permissions
Access control: Handles API access control and rate limiting
Token-based: Uses JWT tokens for secure communication

SIWE Authentication Layer

JWT token generation: Required to obtain JWT tokens for API access
Blockchain verification: Uses cryptographic wallet signing for authentication
Enhanced security: Provides additional security for sensitive operations
Wallet-based: Uses your wallet credentials for comprehensive access
Immutable proof: Creates immutable proof of user intent and authorization
Write operations: Required for the majority of write operations in Rise

API Authentication Requirements

Different API endpoints require different levels of authentication:

JWT Authentication (Read Operations)

User profile information (/me)
Company information (/companies)
Team management (/teams)
Balance queries (/entity-balance)
Transaction history (/transactions)

Note: JWT tokens are obtained through SIWE authentication

Dual Authentication (Sensitive Operations)

Payment processing (/payments)
Withdrawals (/withdrawals)
Manager invites (/invites)
Company settings updates
High-value transactions

Note: These operations require both JWT (obtained via SIWE) and additional SIWE signing

SDK Recommendation: Use the Rise SDK for automatic authentication handling. The SDK will use SIWE to generate JWT tokens and automatically add SIWE signing when required for sensitive operations.

Authentication Flows

Whether you use the SDK or call the API directly, the same handshake runs underneath: ask Rise for a SIWE message, sign it with your wallet, then exchange the signature for a JWT. The SDK does all three steps for you. The JWT is valid for 24 hours. The SDK refreshes it for you; if you drive the handshake yourself, re-run it when the token expires.

SIWE Authentication Flow

The SDK manages the complete SIWE authentication process:

Initialize SDK

Configure the SDK with your Rise ID and private key

Automatic JWT Generation

SDK generates SIWE message, signs it, and obtains JWT token

Token Management

SDK automatically handles JWT token renewal

API Access

Execute API calls with automatic authentication handling

JWT Authentication Flow

For integrations using pre-generated JWT tokens:

Obtain JWT Token

Retrieve JWT token from your existing authentication system

Initialize SDK

Configure the SDK with your JWT token

API Access

Execute API calls with automatic JWT header inclusion

Token Management

Handle token expiration through manual renewal or token refresh

Understanding Authentication

How SIWE Authentication Works

const { ethers } = require('ethers');

// Production: https://integrations-api.riseworks.io
// Staging:    https://integrations-api.staging-riseworks.io
const BASE_URL = 'https://integrations-api.riseworks.io';

async function understandSIWEAuthentication() {
  try {
    const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY);

    // Step 1: Ask Rise for a SIWE message. The wallet address and your
    // personal (user) RiseID both go in the query string.
    const siweResponse = await fetch(
      `${BASE_URL}/v2/auth/siwe?wallet=${wallet.address}&riseid=${process.env.RISE_ID}`
    );

    if (!siweResponse.ok) {
      const { data } = await siweResponse.json();
      throw new Error(`SIWE request failed (${siweResponse.status}): ${data}`);
    }

    const siweData = await siweResponse.json();
    const message = siweData.data.siwe;

    // Step 2: Sign the message with your private key
    const signature = await wallet.signMessage(message);

    // Step 3: Read the nonce back out of the signed message
    const nonce = message.match(/Nonce: (.+)/)?.[1]?.trim();

    // Step 4: Exchange the signature for a JWT
    const verifyResponse = await fetch(`${BASE_URL}/v2/auth/verify`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message, sig: signature, nonce })
    });

    const jwtData = await verifyResponse.json();
    const jwtToken = jwtData.data.jwt;

    console.log('JWT token generated:', jwtToken);
    return jwtToken;

  } catch (error) {
    console.error('SIWE authentication failed:', error.message);
    throw error;
  }
}

// This shows how SIWE authentication works internally
// The Rise SDK handles this automatically for you
const jwtToken = await understandSIWEAuthentication();

How JWT Token Authentication Works

async function understandJWTUsage(jwtToken) {
  try {
    // Use JWT token for API calls
    const response = await fetch('https://integrations-api.riseworks.io/v2/me', {
      method: 'GET',
      headers: {
        'Authorization': `Bearer ${jwtToken}`,
        'Content-Type': 'application/json'
      }
    });

    const userData = await response.json();
    console.log('User data:', userData);
    return userData;

  } catch (error) {
    console.error('API call failed:', error.message);
    throw error;
  }
}

// This shows how JWT authentication works internally
// The Rise SDK handles this automatically for you
const userData = await understandJWTUsage(jwtToken);

SDK Configuration Options

The Rise SDK provides two configuration options to access the APIs:

Using Rise ID and Private Key

Automatic JWT generation: SDK handles SIWE authentication automatically
Comprehensive access: Full access to all API operations
Session management: Automatic JWT token renewal
Wallet-based: Uses your wallet credentials for authentication

Using JWT Token Only

Pre-generated tokens: Use existing JWT tokens for authentication
Basic access: Access to read operations and basic integrations
Simple setup: Direct API access without wallet signing
Limited scope: Cannot perform sensitive operations requiring SIWE

Quick Start with SDK

Using Rise ID Authentication (Recommended)

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

// Initialize with Rise ID and private key for comprehensive API access
const client = new RiseApiClient({
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

// SDK automatically handles both JWT and SIWE authentication
const user = await client.me.get();
console.log('Authenticated as:', user.data.name);

Using JWT Token Authentication

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

// Note: You need to obtain the JWT token manually through SIWE authentication
// or from your existing authentication system before using this approach
// Initialize with JWT token for basic API access
// To get JWT: Use SIWE authentication first, then extract the JWT token
const client = new RiseApiClient({
  jwtToken: process.env.JWT_TOKEN
});

// Ready for read-only operations
const user = await client.me.get();
console.log('Authenticated as:', user.data.name);

const { ethers } = require('ethers');

const BASE_URL = 'https://integrations-api.riseworks.io';

async function generateJwtManually() {
  try {
    const wallet = new ethers.Wallet(process.env.WALLET_PRIVATE_KEY);

    // Step 1: Get a SIWE message
    const siweResponse = await fetch(
      `${BASE_URL}/v2/auth/siwe?wallet=${wallet.address}&riseid=${process.env.RISE_ID}`
    );

    const siweData = await siweResponse.json();
    const message = siweData.data.siwe;

    // Step 2: Sign it, then read the nonce back out of the message
    const signature = await wallet.signMessage(message);
    const nonce = message.match(/Nonce: (.+)/)?.[1]?.trim();

    // Step 3: Verify the signature and get the JWT
    const verifyResponse = await fetch(`${BASE_URL}/v2/auth/verify`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ message, sig: signature, nonce })
    });

    const jwtData = await verifyResponse.json();
    const jwtToken = jwtData.data.jwt;

    console.log('Manually generated JWT token:', jwtToken);
    return jwtToken;

  } catch (error) {
    console.error('JWT generation failed:', error.message);
    throw error;
  }
}

// Usage
const jwtToken = await generateJwtManually();

JWT Token Management

// Store JWT token securely
const jwtToken = await client.getJwtToken();

// Use JWT token for subsequent API calls
const jwtClient = new RiseApiClient({
  jwtToken: jwtToken
});

// Verify JWT token validity
const isValid = await client.isJwtValid();
console.log('JWT token valid:', isValid);

// Refresh JWT token when needed
const newToken = await client.refreshJwtToken();
console.log('New JWT token:', newToken);

SDK Recommendation: Use the SDK’s automatic JWT generation for simplicity. The SDK handles all the complexity of SIWE message generation, signing, and JWT token management for you.

SDK Features

Automatic Token Management

// SDK automatically handles JWT token renewal
const client = new RiseApiClient({
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.WALLET_PRIVATE_KEY
  }
});

// SDK automatically generates new JWT tokens when needed
const user = await client.me.get(); // No manual token management required

Token Generation

// Manually generate JWT token when necessary
const newToken = await client.generateJwtToken();
console.log('New JWT token:', newToken);

Manual Token Refresh

// Manually refresh JWT token when necessary
const newToken = await client.refreshJwtToken();
console.log('New JWT token:', newToken);

Token Validation

// Verify current JWT token validity
const isValid = await client.isJwtValid();
console.log('JWT valid:', isValid);

Error Handling

The SDK provides comprehensive error handling for authentication scenarios:

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

async function handleAuthenticationErrors() {
  try {
    const client = new RiseApiClient({
      riseIdAuth: {
        riseId: process.env.RISE_ID,
        privateKey: process.env.WALLET_PRIVATE_KEY
      }
    });

    const user = await client.me.get();
    console.log('Success:', user.data);

  } catch (error) {
    if (error.message.includes('Rise ID and private key are required')) {
      console.error('Missing credentials - verify your environment variables');
    } else if (error.message.includes('Invalid Rise ID address')) {
      console.error('Invalid Rise ID format - should be 0x + 40 hex characters');
    } else if (error.message.includes('Invalid private key')) {
      console.error('Invalid private key format - should be 0x + 64 hex characters');
    } else if (error.message.includes('401')) {
      console.error('Authentication failed - verify your credentials');
    } else if (error.message.includes('403')) {
      console.error('Permission denied - verify your role permissions');
    } else {
      console.error('Unexpected error:', error.message);
    }
  }
}

Common Error Scenarios

Response	What it means	How to fix
`404` `No entity found with riseid <id>`	The `riseid` isn’t a user RiseID: it carries a network prefix (`arb4:`), is a `us-`/`co-`/`te-` nanoid, or is a company/team RiseID.	Send the bare `0x` user RiseID with the prefix stripped. See Finding your RiseID.
`400` `Wallet address is required` / `riseid is required`	`GET /v2/auth/siwe` was called without the `wallet` or `riseid` query param.	Pass both: `/v2/auth/siwe?wallet=<0x>&riseid=<0x>`.
`403` `Wallet <addr> is not an authorized member of RiseID <id>...`	The wallet you’re signing with holds no Owner, Payer, or Treasurer role on that RiseID.	Authorize the wallet on your RiseID, wait for the on-chain transaction to confirm, then retry. See Authorize your API wallet.
`403` `Company is not enabled for B2B API access`	Your company isn’t enabled for the B2B API in this environment.	Ask Rise to enable it for the environment you’re calling. Staging and production are separate. See Enable your company.
`401 Unauthorized`	The JWT is missing, expired, or invalid.	Re-run the SIWE handshake for a fresh token. The SDK does this for you.
`Invalid Rise ID address`	Rise ID isn’t in the right format.	A Rise ID starts with `0x` and is 42 characters.
`Invalid private key`	Private key isn’t in the right format.	A private key starts with `0x` and is 66 characters.

Security Best Practices

Recommended Practices:

Use environment variables for all sensitive data
Use secondary wallets for API operations
Implement comprehensive error handling

Security Considerations:

Never store private keys in code
Never commit credentials to version control
Avoid using main wallets with significant funds for API operations
Never ignore authentication errors

Next Steps

Private Keys Guide

Learn how to get and use private keys

Secondary Wallets

Use dedicated wallets for API operations

SDK Examples

See more SDK usage examples

Security Best Practices

Comprehensive security guidelines

Ready to integrate? Review our Quickstart Guide to begin using the Rise SDK with authentication.

​Authentication

SIWE Authentication

JWT Authentication

​Authentication Layers

​JWT Authentication Layer

​SIWE Authentication Layer

​API Authentication Requirements

​JWT Authentication (Read Operations)

​Dual Authentication (Sensitive Operations)

​Authentication Flows

​SIWE Authentication Flow

​JWT Authentication Flow

​Understanding Authentication

​How SIWE Authentication Works

​How JWT Token Authentication Works

​SDK Configuration Options

​Using Rise ID and Private Key

​Using JWT Token Only

​Quick Start with SDK

​Using Rise ID Authentication (Recommended)

​Using JWT Token Authentication

​JWT Token Management

​SDK Features

​Automatic Token Management

​Token Generation

​Manual Token Refresh

​Token Validation

​Error Handling

​Common Error Scenarios

​Security Best Practices

​Recommended Practices:

​Security Considerations:

​Next Steps

Private Keys Guide

Secondary Wallets

SDK Examples

Security Best Practices

Authentication

Authentication Layers

JWT Authentication Layer

SIWE Authentication Layer

API Authentication Requirements

JWT Authentication (Read Operations)

Dual Authentication (Sensitive Operations)

Authentication Flows

SIWE Authentication Flow

JWT Authentication Flow

Understanding Authentication

How SIWE Authentication Works

How JWT Token Authentication Works

SDK Configuration Options

Using Rise ID and Private Key

Using JWT Token Only

Quick Start with SDK

Using Rise ID Authentication (Recommended)

Using JWT Token Authentication

JWT Token Management

SDK Features

Automatic Token Management

Token Generation

Manual Token Refresh

Token Validation

Error Handling

Common Error Scenarios

Security Best Practices

Recommended Practices:

Security Considerations:

Next Steps