Managing Roles

This guide covers how to assign roles to team members, change existing role assignments, and understand how roles interact with your billing platform.

Assigning a Role to a User

1. Navigate to Settings > IAM > Users
2. Click Add User or select an existing user
3. In the user detail panel, select one or more roles from the Roles dropdown
4. Click Save

The user will have access to the resources defined by their assigned role(s) on their next login.

Changing a User’s Role

1. Navigate to Settings > IAM > Users
2. Select the user whose role you want to change
3. Update the Roles dropdown — add new roles or remove existing ones
4. Click Save

Role changes take effect on the user’s next API request. Active sessions will use the updated permissions automatically.

Multiple Roles

A user can have more than one role. When a user has multiple roles, access is additive — they get the combined permissions of all assigned roles.

Example: A user with both Finance Manager and Customer Success Manager roles can:

• Manage invoices and payments (from Finance Manager)
• Create orders and manage contacts (from Customer Success Manager)
• Manage customers and subscriptions (from both roles)

Role Visibility in the UI

Assigned roles are displayed in several places:

• User Profile — The My Profile page shows role badges for the logged-in user
• Dashboard Header — Role badges appear in the sidebar user panel
• IAM Users List — Each user’s assigned roles are shown in the users table

Only BillHive application roles are displayed. Internal system roles (such as Keycloak client roles) are filtered out automatically.

Best Practices

Principle of Least Privilege

Assign the most restrictive role that still allows the user to do their job:

• Start with Support Agent for new team members and escalate as needed
• Use Administrator sparingly — only for team members who need full platform control
• Reserve Owner for the business owner or primary account holder

Role Assignment by Team

Periodic Review

Review role assignments quarterly to ensure:

• Departed team members have been removed
• Role assignments still match current responsibilities
• No user has more access than they need

Troubleshooting

User gets 403 Forbidden

If a user receives a 403 Forbidden error when accessing a resource:

1. Check role assignment — Verify the user has a role that grants access to the requested resource. See the Permission Matrix for the full mapping.
2. Check login session — Ask the user to log out and log back in to refresh their token with updated role claims.
3. Verify role in Keycloak — In the Keycloak admin console, confirm the user has the correct client role assigned under the BillHive client (not just a realm role).

User sees internal roles in profile

If roles like view-clients, manage-account, or query-clients appear in a user’s profile, this indicates the role filter is not applied. Only roles defined in the BillHive application role set should be displayed. Contact your administrator if this occurs.

Related Topics

• Roles — Detailed breakdown of each role
• Permission Matrix — Full resource-by-role access matrix