Team Management Guide - Rise B2B API

Learn how to manage teams and users with the Rise B2B API using the official SDK. The SDK provides methods for team updates, user management, and team invitations.

Team Management Flow

Initialize SDK

Set up the Rise SDK with authentication

Get User Teams

Retrieve teams associated with the current user

Update Team Settings

Modify team information and settings

Manage Team Members

Send invitations and manage team membership

SDK Installation

First, install the Rise SDK:

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

Getting Started

Initialize the SDK

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
});

Team Management Operations

Get User’s Teams

Retrieve all teams associated with the current user:

// Get all teams for the current user
const teams = await client.user.getTeams();
console.log('User teams:', teams.data);

// Example response structure
// {
//   "success": true,
//   "data": {
//     "teams": [
//       {
//         "nanoid": "te-abc123def456",
//         "name": "Engineering Team",
//         "description": "Core engineering team",
//         "member_count": 5,
//         "status": "active"
//       }
//     ]
//   }
// }

Update Team Information

Update team settings and information:

// Update team information
await client.team.update({
  nanoid: 'te-abc123def456',
  name: 'Updated Engineering Team',
  description: 'Updated team description'
});

console.log('Team updated successfully');

Team Invitations

The SDK provides different approaches for sending team invitations depending on the role:

Regular Team Invitations

For regular team members (employees, viewers), no signing is required:

// Send invitation to regular team members (no signing required)
const invitation = await client.invites.send({
  nanoid: 'te-abc123def456',
  invites: [
    {
      email: 'john.doe@example.com',
      role: 'team_employee',
      permissions: ['pay', 'view']
    },
    {
      email: 'jane.smith@example.com',
      role: 'team_viewer',
      permissions: ['view']
    }
  ],
  role: 'team_employee',
  anonymous: false
});

console.log('Invitations sent:', invitation.data);

What the SDK does automatically:

Validates invitation data and permissions
Sends invitations to the specified email addresses
Handles authentication and JWT token management
Provides error handling and validation

Manager Invitations (Requires Signing)

For manager-level invitations (team_admin, finance_admin), signing is required. The SDK must be initialized with a private key for automatic signing:

// Initialize SDK with private key for automatic signing
const client = new RiseApiClient({
  environment: 'prod',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.PRIVATE_KEY  // Required for automatic signing
  }
});

// Send manager invitation with automatic signing
const managerInvite = await client.invites.sendManagerInvite({
  emails: ['manager@example.com'],
  role: 'team_admin',
  nanoid: 'te-abc123def456'
});

console.log('Manager invitation sent:', managerInvite.data);

What the SDK does automatically:

Generates typed data for EIP-712 signing
Signs the typed data using your private key
Submits the signed invitation to the Rise API
Handles authentication and JWT token management
Provides error handling and retry logic

Manual Manager Invitations

For more control over manager invitation signing, you can handle the signing manually:

// Initialize SDK (private key not required for manual flow)
const client = new RiseApiClient({
  environment: 'prod',
  jwtToken: process.env.JWT_TOKEN  // JWT token is sufficient for manual flow
});

// Step 1: Get typed data for signing
const typedDataResponse = await client.invites.getManagerInviteTypedData({
  emails: ['manager@example.com'],
  role: 'team_admin',
  nanoid: 'te-abc123def456'
});

console.log('Typed data received:', typedDataResponse.data);

// Step 2: Sign the typed data (if you want custom signing logic)
const { ethers } = require('ethers');
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY);
const signature = await wallet.signTypedData(
  typedDataResponse.data.typed_data.domain,
  typedDataResponse.data.typed_data.types,
  typedDataResponse.data.typed_data.typed_data
);

// Step 3: Execute with signature
const executeResponse = await client.invites.executeManagerInviteWithSignedData({
  invites: typedDataResponse.data.invites,
  signer: wallet.address,
  typed_data: typedDataResponse.data.typed_data.typed_data,
  signature: signature
});

console.log('Manager invitation executed:', executeResponse.data);

What the manual flow provides:

Custom signing logic - You control when and how to sign
Typed data inspection - You can examine the data before signing
Signature verification - You can verify the signature before submission
Error handling control - Custom error handling for each step
Integration flexibility - Easier integration with existing signing workflows

Complete Team Management Example

Here’s a complete example using the Rise SDK:

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

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

  async getUserTeams() {
    try {
      const teams = await this.client.user.getTeams();
      return teams.data;
    } catch (error) {
      console.error('Failed to get user teams:', error.message);
      throw error;
    }
  }

  async updateTeam(teamNanoid, updates) {
    try {
      await this.client.team.update({
        nanoid: teamNanoid,
        ...updates
      });
      console.log('Team updated successfully');
    } catch (error) {
      console.error('Failed to update team:', error.message);
      throw error;
    }
  }

  async inviteTeamMembers(teamNanoid, members) {
    try {
      const invitation = await this.client.invites.send({
        nanoid: teamNanoid,
        invites: members,
        role: 'team_employee',
        anonymous: false
      });
      
      console.log('Team invitations sent:', invitation.data);
      return invitation.data;
    } catch (error) {
      console.error('Failed to send invitations:', error.message);
      throw error;
    }
  }

  async inviteManager(teamNanoid, email, role = 'team_admin') {
    try {
      const managerInvite = await this.client.invites.sendManagerInvite({
        emails: [email],
        role: role,
        nanoid: teamNanoid
      });
      
      console.log('Manager invitation sent:', managerInvite.data);
      return managerInvite.data;
    } catch (error) {
      console.error('Failed to send manager invitation:', error.message);
      throw error;
    }
  }

  async getTeamInvites(teamNanoid) {
    try {
      const invites = await this.client.invites.get({
        nanoid: teamNanoid
      });
      return invites.data;
    } catch (error) {
      console.error('Failed to get team invites:', error.message);
      throw error;
    }
  }
}

// Usage example
const teamManager = new RiseTeamManager();

async function main() {
  try {
    // Get user's teams
    const teams = await teamManager.getUserTeams();
    console.log('User teams:', teams);

    if (teams.teams && teams.teams.length > 0) {
      const firstTeam = teams.teams[0];

      // Update team information
      await teamManager.updateTeam(firstTeam.nanoid, {
        name: 'Updated Engineering Team',
        description: 'Updated team description'
      });

      // Invite new team members
      const newMembers = [
        {
          email: 'developer1@example.com',
          role: 'team_employee',
          permissions: ['pay', 'view']
        },
        {
          email: 'developer2@example.com',
          role: 'team_employee',
          permissions: ['pay', 'view']
        }
      ];

      await teamManager.inviteTeamMembers(firstTeam.nanoid, newMembers);

      // Invite a manager
      await teamManager.inviteManager(
        firstTeam.nanoid,
        'manager@example.com',
        'team_admin'
      );

      // Get team invitations
      const invites = await teamManager.getTeamInvites(firstTeam.nanoid);
      console.log('Team invitations:', invites);
    }

  } catch (error) {
    console.error('Team management error:', error.message);
  }
}

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

Team Roles and Permissions

Role	Permissions	Description
Team Admin	`pay`, `view`, `manage`, `invite`	Full control over team settings and members
Finance Admin	`pay`, `view`, `finance`	Financial management capabilities
Team Employee	`pay`, `view`	Standard team member with payment capabilities
Team Viewer	`view`	Read-only access to team information

Error Handling

The SDK provides comprehensive error handling:

try {
  const teams = await client.user.getTeams();
  console.log('Teams retrieved successfully:', teams.data);
} catch (error) {
  console.error('Team management error:', error.message);
  
  // Handle specific error types based on message content
  if (error.message.includes('401')) {
    console.error('Authentication failed');
  } else if (error.message.includes('403')) {
    console.error('Insufficient permissions for this operation');
  } else if (error.message.includes('404')) {
    console.error('Team not found');
  } else if (error.message.includes('invalid')) {
    console.error('Invalid team data provided');
  } else {
    console.error('Team operation failed:', error.message);
  }
}

Common team management errors:

Error Message	Description	Solution
`401`	Authentication failed	Check your credentials and JWT token
`403`	Insufficient permissions	Verify user has required role and permissions
`404`	Team not found	Check team nanoid is correct
`invalid team data`	Invalid team information	Verify team data format and requirements
`invitation failed`	Failed to send invitation	Check email format and team permissions

Best Practices

Always maintain at least one team admin to prevent losing access to team management capabilities.

Team Management Best Practices

Role Hierarchy: Use the principle of least privilege when assigning roles
Regular Audits: Periodically review team members and their permissions
Documentation: Keep records of team structure and permission changes
Backup Admins: Always have multiple admins for critical teams
Permission Reviews: Regularly review and update member permissions

SDK Best Practices

Error Handling: Implement proper error handling for all team operations
Authentication: Use Rise ID authentication for automatic JWT management
Environment: Use staging environment for testing team operations
Logging: Log team management operations for audit purposes

Testing Team Management

For testing, use the staging environment:

// Staging configuration for testing
const stagingClient = new RiseApiClient({
  environment: 'stg',
  riseIdAuth: {
    riseId: process.env.RISE_ID,
    privateKey: process.env.PRIVATE_KEY
  }
});

// Test team operations
const testTeams = await stagingClient.user.getTeams();
console.log('Test teams:', testTeams.data);

Next Steps

Authentication Guide

Learn how to authenticate with Rise using the SDK

Payment Integration

Process payments for team members

Web3 Integration

Advanced blockchain integration features

Error Handling

Comprehensive error handling and troubleshooting

Need help? See the Teams page for detailed team management concepts or contact support at Hello@Riseworks.io

​Team Management Flow

​SDK Installation

​Getting Started

​Initialize the SDK

​Team Management Operations

​Get User’s Teams

​Update Team Information

​Team Invitations

​Regular Team Invitations

​Manager Invitations (Requires Signing)

​Manual Manager Invitations

​Complete Team Management Example

​Team Roles and Permissions

​Error Handling

​Best Practices

​Team Management Best Practices

​SDK Best Practices

​Testing Team Management

​Next Steps

Authentication Guide

Payment Integration

Web3 Integration

Error Handling

Team Management Flow

SDK Installation

Getting Started

Initialize the SDK

Team Management Operations

Get User’s Teams

Update Team Information

Team Invitations

Regular Team Invitations

Manager Invitations (Requires Signing)

Manual Manager Invitations

Complete Team Management Example

Team Roles and Permissions

Error Handling

Best Practices

Team Management Best Practices

SDK Best Practices

Testing Team Management

Next Steps