Team Management Guide

Manage teams and users with Rise B2B API

Learn how to create, update, and manage teams and users with the Rise B2B API.

Team Management Flow

1. Create Team

   Create a new team with name and admin wallet

2. Add Members

   Invite users with specific roles and permissions

3. Manage Roles

   Update member roles and permissions

4. Remove Members

   Remove users from teams when needed

API Examples

Create a Team

Request

curl -X POST "${this.baseUrl}/v2/teams" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Team",
    "description": "Core engineering team for product development",
    "entity_nanoid": "entity_123",
    "admin_wallet": "0x1234567890abcdef..."
  }'

Response

{
  "success": true,
  "data": {
    "team_nanoid": "te-abc123def456",
    "name": "Engineering Team",
    "description": "Core engineering team for product development",
    "entity_nanoid": "entity_123",
    "admin_wallet": "0x1234567890abcdef...",
    "created_at": "2024-01-01T12:00:00Z",
    "member_count": 1,
    "status": "active"
  }
}

Add a User to a Team

Request

curl -X POST "${this.baseUrl}/v2/teams/te-abc123def456/members" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_nanoid": "us-ghi789jkl012",
    "role": "team_employee",
    "permissions": ["pay", "view"]
  }'

Update Team Settings

Request

curl -X PUT "${this.baseUrl}/v2/teams/te-abc123def456/settings" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Engineering Team",
    "description": "Updated team description"
  }'

Remove a User

Request

curl -X DELETE "${this.baseUrl}/v2/teams/te-abc123def456/members/us-ghi789jkl012" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Complete Integration Example

const { ethers } = require('ethers');
require('dotenv').config();

class RiseTeamManagement {
  constructor(baseUrl, jwtToken) {
    this.baseUrl = baseUrl;
    this.headers = {
      'Authorization': `Bearer ${jwtToken}`,
      'Content-Type': 'application/json'
    };
  }

  async createTeam(name, description, entityNanoid, adminWallet) {
    const teamData = {
      name,
      description,
      entity_nanoid: entityNanoid,
      admin_wallet: adminWallet
    };

    const response = await fetch(`${this.baseUrl}/v2/teams`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(teamData)
    });

    return response.json();
  }

  async getTeam(teamNanoid) {
    const response = await fetch(
      `${this.baseUrl}/v2/teams/${teamNanoid}`,
      { headers: this.headers }
    );
    return response.json();
  }

  async addMember(teamNanoid, userNanoid, role, permissions) {
    const memberData = {
      user_nanoid: userNanoid,
      role,
      permissions
    };

    const response = await fetch(`${this.baseUrl}/v2/teams/${teamNanoid}/members`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(memberData)
    });

    return response.json();
  }

  async updateMemberRole(teamNanoid, userNanoid, newRole, newPermissions) {
    const updateData = {
      role: newRole,
      permissions: newPermissions
    };

    const response = await fetch(`${this.baseUrl}/v2/teams/${teamNanoid}/members/${userNanoid}`, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(updateData)
    });

    return response.json();
  }

  async removeMember(teamNanoid, userNanoid) {
    const response = await fetch(`${this.baseUrl}/v2/teams/${teamNanoid}/members/${userNanoid}`, {
      method: 'DELETE',
      headers: this.headers
    });

    return response.json();
  }

  async updateTeamSettings(teamNanoid, settings) {
    const response = await fetch(`${this.baseUrl}/v2/teams/${teamNanoid}/settings`, {
      method: 'PUT',
      headers: this.headers,
      body: JSON.stringify(settings)
    });

    return response.json();
  }
}

// Usage example
async function main() {
  const teamManagement = new RiseTeamManagement(
    'your-base-url', // Configure for your environment
    process.env.JWT_TOKEN
  );

  try {
    // Create a new team
    const newTeam = await teamManagement.createTeam(
      'Engineering Team',
      'Core engineering team for product development',
      'entity_123',
      process.env.ADMIN_WALLET
    );
    
    console.log('Team created:', newTeam.data.team_nanoid);

    // Add a member to the team
    const memberAdded = await teamManagement.addMember(
      newTeam.data.team_nanoid,
      'us-ghi789jkl012',
      'team_employee',
      ['pay', 'view']
    );
    
    console.log('Member added successfully');

    // Update team settings
    const updatedTeam = await teamManagement.updateTeamSettings(
      newTeam.data.team_nanoid,
      {
        name: 'Updated Engineering Team',
        description: 'Updated team description'
      }
    );
    
    console.log('Team settings updated');

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

// 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

Common team management errors and solutions:

Error	Description	Solution
INVALID_TEAM_NAME	Team name is invalid or too long	Use a valid team name (2-50 characters)
INVALID_ADMIN_WALLET	Admin wallet address is invalid	Ensure wallet address is valid Ethereum address
INSUFFICIENT_PERMISSIONS	User lacks permission for action	Check user’s role and permissions
TEAM_NOT_FOUND	Team does not exist	Verify team_nanoid is correct
MEMBER_ALREADY_EXISTS	User is already a team member	Check existing team membership
CANNOT_REMOVE_ADMIN	Cannot remove the last admin	Ensure at least one admin remains

Best Practices

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

• 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

Need help? See the Teams page for detailed team management concepts or contact support at [e-mail]