> ## 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. # Roles & Permissions > Understanding role-based access control and permissions in Rise B2B API Rise B2B API implements a comprehensive role-based access control (RBAC) system that defines what users can do within companies and teams. Understanding these roles is essential for building secure integrations. ## Role Hierarchy Rise uses a hierarchical permission system where company roles cascade down to team roles: Organization-wide roles that control company settings and team access Team-specific roles that control team operations and member management ## Company Roles Company roles provide organization-wide permissions and automatically cascade to teams within the company. ### Company Owner (`company`) * **Full control** over the entire company * Can manage all company settings and configurations * Controls all teams and their members * Can assign and revoke any role within the company * Access to all company features and data ### Organization Admin (`org_admin`) * **Administrative control** over company operations * Can manage company settings and team configurations * Can invite and manage team members across all teams * Controls company-wide payment and financial settings * Cannot modify company ownership or core structure ### Organization Finance Admin (`org_finance_admin`) * **Financial management** capabilities across all teams * Can create and execute payments for any team * Manages company budgets and spending limits * Can view financial reports and transaction history * Cannot modify team structure or member permissions ### Organization Viewer (`org_viewer`) * **Read-only access** to company information * Can view company details, teams, and financial data * Cannot create payments or modify any settings * Useful for auditors, accountants, or stakeholders ## Team Roles Team roles provide granular control over specific team operations and member management. ### Team Admin (`team_admin`) * **Full control** over team settings and members * Can create, modify, and delete team configurations * Manages team funds and payment limits * Can invite and remove team members * Access to all team features and data ### Team Finance Admin (`team_finance_admin`) * **Financial management** capabilities for the team * Can create and execute payments for the team * Manages team budgets and spending limits * Can view team financial reports and transaction history * Cannot modify team structure or invite new members ### Team Employee (`team_employee`) * **Standard team member** with payment capabilities * Can create and execute payments within team limits * Access to team funds for authorized transactions * Can view relevant team information * Cannot modify team settings or invite new members ### Team Viewer (`team_viewer`) * **Read-only access** to team information * Can view team members, payments, and balances * Cannot create payments or modify any settings * Useful for auditors, accountants, or stakeholders ### Contractor (`contractor`) * **External contractor** with limited team access * Can receive payments from the team * Limited access to team information * Cannot create payments or modify team settings ## Role Permissions Matrix ### Company-Level Permissions | Permission | Company Owner | Org Admin | Org Finance Admin | Org Viewer | | --------------------------- | ------------- | --------- | ----------------- | ---------- | | **View Company** | ✅ | ✅ | ✅ | ✅ | | **Manage Company Settings** | ✅ | ✅ | ❌ | ❌ | | **Manage Teams** | ✅ | ✅ | ❌ | ❌ | | **Company Payments** | ✅ | ✅ | ✅ | ❌ | | **Invite Members** | ✅ | ✅ | ❌ | ❌ | | **Manage Roles** | ✅ | ✅ | ❌ | ❌ | | **View Financial Data** | ✅ | ✅ | ✅ | ✅ | ### Team-Level Permissions | Permission | Team Admin | Finance Admin | Employee | Viewer | Contractor | | ------------------------ | ---------- | ------------- | -------- | ------ | ---------- | | **View Team** | ✅ | ✅ | ✅ | ✅ | ✅ | | **Manage Team Settings** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Team Payments** | ✅ | ✅ | ✅ | ❌ | ❌ | | **Invite Members** | ✅ | ❌ | ❌ | ❌ | ❌ | | **Manage Roles** | ✅ | ❌ | ❌ | ❌ | ❌ | | **View Financial Data** | ✅ | ✅ | ✅ | ✅ | ❌ | ## Role Hierarchy & Cascading ### Company to Team Role Mapping When a user has a company role, it automatically grants them corresponding team roles: Company roles automatically grant equivalent team permissions across all teams in the organization ## How Roles Work in the API ### Permission Validation The B2B API uses **permission validation** rather than role queries. When you make API calls, the system automatically checks if your user has the required permissions. If you lack permission, the API returns a 403 Forbidden error with details about what role is required. ### Error-Based Permission Discovery Since there's no direct role query endpoint, you can discover user permissions through API responses. When an API call fails with a 403 error, the response will indicate what role is required for that operation. ## Role Management ### Assigning Roles Roles can be assigned through the invite system using the `/v2/invites/manager` endpoint. ### Role Settings You can access role-specific settings for team members using the team member settings endpoints. ## Security Best Practices * Assign the minimum role required for each user * Regularly review and audit role assignments * Remove unnecessary permissions promptly * Rotate admin roles regularly * Have multiple admins for critical operations * Document role changes for audit trails * Monitor role assignments and changes * Log all permission-related activities * Set up alerts for suspicious role changes * Conduct regular permission audits * Review inactive user permissions * Validate role assignments against business needs ## Error Handling Common role-related errors and solutions: | HTTP Status | Error | Description | Solution | | ----------- | -------------------------- | -------------------------------------------- | ----------------------------------------------- | | `403` | `INSUFFICIENT_PERMISSIONS` | User lacks required role | Check user's current role and upgrade if needed | | `400` | `INVALID_ROLE` | Role doesn't exist or is invalid | Use one of the valid role types | | `404` | `USER_NOT_FOUND` | User doesn't exist in the entity | Verify user is a member of the entity | | `409` | `ROLE_CONFLICT` | Role assignment conflicts with existing role | Remove existing role before assigning new one | ### Common Error Scenarios **Insufficient Permissions (403):** ```json theme={null} { "success": false, "data": "User us-abc123def456 must have admin access to team te-xyz789abc123. Current role: team_viewer" } ``` **Invalid Role Assignment (400):** ```json theme={null} { "success": false, "data": "Invalid role: super_admin. Valid roles are: team_admin, team_finance_admin, team_viewer" } ``` ## Real-World Role Scenarios ### Startup Organization **Company Level:** * **Founder**: `company` role with full control * **Co-founder**: `org_admin` role for administrative control * **Accountant**: `org_finance_admin` role for financial management * **Investor**: `org_viewer` role for read-only access **Team Level:** * **Engineering Lead**: `team_admin` role for team management * **Senior Developer**: `team_employee` role for standard operations * **Intern**: `team_viewer` role for limited access ### Enterprise Organization **Company Level:** * **CEO**: `company` role with full control * **CTO**: `org_admin` role for technical operations * **CFO**: `org_finance_admin` role for financial management * **Auditor**: `org_viewer` role for compliance monitoring **Department Level:** * **Engineering Director**: `team_admin` role for engineering team * **Finance Manager**: `team_finance_admin` role for finance team * **HR Director**: `team_admin` role for HR team ## Related Concepts Understanding team management Balance management and permissions SIWE authentication and role validation Role assignment through invites **Role Discovery**: Since there's no direct role query endpoint, you can discover user permissions by attempting API calls and handling 403 errors appropriately. The API will automatically validate permissions for each operation.