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

# 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

<Steps>
  <Step title="Install SDK">
    Install the Rise SDK package
  </Step>

  <Step title="Configure Authentication">
    Set up SDK with Rise ID and private key or JWT token
  </Step>

  <Step title="Automatic Authentication">
    SDK handles SIWE signing and JWT token management
  </Step>

  <Step title="API Access">
    Execute API calls with automatic authentication
  </Step>
</Steps>

## SDK Installation

First, install the Rise SDK:

```bash theme={null}
npm install @riseworks/riseworks-sdk
# Or: yarn add @riseworks/riseworks-sdk
# Or: pnpm add @riseworks/riseworks-sdk
```

## Complete Integration Example

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

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

<Warning>
  **Never expose private keys** in client-side code or commit them to version control.
</Warning>

### Secondary Wallets

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

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

<CardGroup cols={2}>
  <Card title="Payment Integration" icon="credit-card" href="/guides/payment-integration">
    Learn how to process payments with automatic authentication
  </Card>

  <Card title="Team Management" icon="users" href="/guides/team-management">
    Manage teams and permissions with the SDK
  </Card>

  <Card title="Webhooks" icon="webhook" href="/webhooks/getting-started/overview">
    Set up real-time notifications for your integration
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/guides/error-handling">
    Comprehensive error handling and troubleshooting
  </Card>
</CardGroup>

<Note>
  **Need help?** See the [Authentication](/authentication) page for detailed documentation or contact support at [Hello@Riseworks.io](mailto:Hello@Riseworks.io)
</Note>