Important Update: Staff API Changes & New Permissions Framework

We’re excited to announce our new Roles & Permissions (R&P) Framework. These changes are designed to provide more flexibility, security, and scalability for managing access. Here’s a detailed breakdown of what’s changing and why it matters.

The New Permissions Framework

Our new R&P infrastructure fundamentally shifts how access is managed. Instead of relying on static role assignments, permissions are now the primary mechanism for determining what actions a user can perform. Key features include:

Permission-Based Access:
- Access decisions are made based on specific permissions rather than roles. For example, if a user lacks permission to access the payment module, they won't be able to export payments, even if their role traditionally allows it.
Categorized Permissions:
- Permissions are grouped into categories, making it easier to manage access granularly.
Flexible Role Management:
- While the Admin and User roles remain system-defined and non-editable, businesses can now customize all other roles to better suit their needs.
- Users will be able to create new custom roles.
- Admins can customize specific permissions for staff members on top of their role assignments.
OpenFGA-Backed Infrastructure:
- Our new backend leverages OpenFGA for better performance, enhanced security, and scalability. This ensures faster access checks, even as your organization scales.

Benefits:

Greater Customization: Businesses can define and adjust roles as needed, offering flexibility to tailor access control.
Scalability and Speed: The new system is optimized for performance, even with high user volumes or complex role configurations.
Improved Security: We reduce the risk of over-permissioned users gaining unintended access by checking specific permissions rather than roles.
Enhanced Visibility: Permissions are now explicit, making it easier to audit and understand who can access what.
Improved Integrations: A new set of platform API's enables partners to easily create, get and set roles and permissions to staff members

Staff API Changes

To align with the new framework, we are updating the Staff API as follows:

Deprecating therole Field:
- The role field should no longer be relied upon for checking permissions. Roles are now customizable, meaning access is not strictly tied to them. As such, this field will soon be deprecated.
- For users with custom roles, the role field will return null.
Newdisplay_name Property:
- We’re introducing a display_name property in the Staff GET APIs to provide a clear and user-friendly identifier for staff members.
Using the New R&P APIs:
- Replace all role-based access checks with permission-based checks using the new R&P APIs. These APIs allow you to query specific permissions directly, ensuring accurate access control. Learn more about the new APIs here: Roles & Permissions Overview.

Relevant APIs: https://developers.intandem.tech/reference/staff

Transition Timeline

The rollout of these changes is happening in phases:

Migration & Testing: Already underway, completed by January 12, 2024.
Infrastructure Rollout: January 21–February 9, 2025.
New UI Rollout: Starting January 23, 2025.

For more details, refer to our [Roles & Permissions Rollout Plan](Roles & Permissions - Rollout plan.pdf).

What You Need to Do

Update your systems to stop relying on the role field for permissions checks.
Integrate the new R&P APIs to query specific permissions for access decisions.
Familiarize yourself with the display_name property for better staff identification. (will be available January 15, 2024)

We’re committed to making this transition seamless. If you have any questions or need support, please don’t hesitate to reach out. Let’s build a more secure and scalable future together!