Multi-Role Users in Clever

Clever users, such as teachers, staff, and district admins, can often hold multiple roles within a district. For example, a user might be both a teacher and a school administrator, or a district admin who also teaches a class.

With API v3.x, user roles are no longer mutually exclusive. Your app must gracefully handle these multi-role scenarios to ensure users have the correct permissions, access, and experience based on their complete role profile.

Why Multi-Role Handling Matters:

• Reflects real-world district structures where users hold overlapping responsibilities.
• Avoids blocking users from functionality tied to only one of their roles.
• Supports flexible permissions, accurate reporting, and user-friendly UX.

Understanding the API v3.x User Model

• Users are returned from the /v3.1/users or /v3.1/users/{id} endpoint.
• The user id will need to be used in all calls that require a specific user's ID - not the legacy_id.
• Each user has a roles array indicating one or more role types.
• Each role includes:
  • type (e.g., "teacher", "student", "school_admin", "district_admin")
  • Associated schools array (for school-scoped roles)
  • Role-specific metadata

🚧

Looking to pull users in bulk?

Requests made to the /v3.1/users endpoint must be authorized with the district-app token and will only return results for Secure Sync apps.

If your application only supports District SSO or the Clever Library, you will need to call the /v3.1/users/{id} endpoint and authorize with the SSO Bearer access_token.

Multi-Role users and the schools array

In Clever API v3.x, roles like teacher and staff are scoped to specific schools in the roles array. This is clear in the response format from the /v3.0/users endpoint, where each role can include a schools array, indicating which school(s) that role applies to.

Condensed example record for a user that has the teacher and staff roles in Clever:

{
    "data": {
        "district": "6385008f69df036e83e984a3",
        "email": "[email protected]",
        "name": {
            "first": "Danny",
            "last": "Brakus",
            "middle": "D"
        },
        "id": "67290af290b55408fa4b09e7",
        "roles": {
            "teacher": {
                "school": "63850203bfb8460546071e60",
                "schools": [
                    "63850203bfb8460546071e60"
                ],
                "sis_id": "42",
                "legacy_id": "67290af290b55408fa4b09e3"
            },
            "staff": {
                "roles": [
                    "PortalOnly"
                ],
                "schools": [
                    "63850203bfb8460546071e5e"
                ],
                "staff_id": "74002",
                "legacy_id": "67feda77ecb57b200c573ce6"
            }
        }
    }

This implies that:

• A user may be a teacher at one school, but not another.
• A user may be an admin (staff) at multiple schools, and your app might need to know which school context a given role applies to.

Exceptions and Considerations

• This school scoping does not apply to roles like district_admin, which are inherently district-wide and don’t list schools.
• For students and teachers, the schools array specifies all school IDs their sections are associated with, which by extension associates them with that school site. See this Help Center article for more information on primary school assignments in Clever.
• students and teachers will have a school field, in addition to the schools array on their record. If your app requires a primary school association for these users, you should use the school field, not the schools array. See the teacher role in the above example for additional context.
• staff users in Clever cannot have a primary school assigned to them in the same was as a student or teacher user, and as such, do not have a school field under their role - only a schools array.

Implementation Recommendations

1. Always Assume Multiple Roles

User with a student or contact role in Clever cannot hold multiple roles. For all other user types, it should be assumed that they have multiple roles, and your application should iterate through all available roles to better understand the user's context.

2. Choose a Multi-Role Handling Strategy

There are two common approaches to handling multi-role users in your app:

• Option 1: Consolidate Roles into One Account
  • Treat all roles as belonging to a single user account.
  • Dynamically adjust the user experience based on available roles.
  • This option is ideal for apps that support unified views or role-aware permissions.
• Option 2: Role-Specific Accounts
  • Create separate accounts per role.
  • Let users switch between roles in your UI (e.g., teacher view vs. admin view).
  • Useful if different roles have fundamentally different workflows.

3. Assigning Permissions and Access

Determine how roles map to your app's permission system. Consider:

• Granting permissions based on the most privileged role (e.g., if district admin, full access).
• Letting District Admins assign roles manually within your app, based on your use case.

4. UI Tips for Multi-Role Users

• Display combined access where applicable (e.g., teacher + admin capabilities).
• Or provide a role switcher UI:

"You're logged in as a Teacher. Switch to Admin view →"

5. Graceful SSO Handling

• Clever SSO identifies users as a type on the /me endpoint, but does not specify a role on login.
• Your app is responsible for determining available roles for the user and handling routing or context accordingly.

FAQs

Q: Do users have a primary role?

A: No. The roles array includes all roles the user holds. There’s no designated "primary" role in Clever v3.x.

Q: Should I consolidate or separate user accounts per role?

A: It depends on your app. For simplicity and usability, most apps consolidate. But if roles have distinct workflows, role-specific accounts may be better—with a clean way for users to switch views.

Q: What if I’m upgrading from v2.x?

A: You’ll likely need to refactor logic that assumes a single role per user account/ID, update permission systems, and user IDs for teacher, staff, and district admin users.

Q: Can contacts have multiple roles?

A: Contacts are provided with a multi-role user ID, same as the other user types, however, contacts cannot be assigned multiple roles in a district. For example, if a teacher is also a contact in the district, you will see two records: one for their teacher record, and one for their contact record, each with their own Clever User ID.