Multi-Role Users in Clever

Use this page to understand how multi-role users are represented in Clever API v3.x and choose a strategy for handling them in your app.

Overview

Clever users such as teachers, staff, and district admins can 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.

In API v3.x, user roles are no longer mutually exclusive. Your app should handle these cases gracefully so users receive the correct permissions, access, and experience based on their full role profile.

Why multi-role handling matters

Handling multi-role users well helps your app:

• reflect how real districts assign overlapping responsibilities
• avoid blocking users from functionality tied to one of their roles
• support clearer permissions, reporting, and user experience

Understanding the API v3.x user model

Users are returned from:

• /v3.1/users
• /v3.1/users/{id}

When you need a specific user ID for later API calls, use the user’s top-level id, not the legacy_id.

Each user has a roles object that can contain one or more role types. Each role includes role-specific fields such as:

• role type
• associated schools values for school-scoped roles
• role-specific metadata
• legacy_id

🚧

Looking to pull users in bulk?

Requests to /v3.1/users must be authorized with a district-app token and only return results for Clever Secure Sync apps.

If your app only supports Clever Single Sign-On or Clever Library, call /v3.1/users/{id} with the SSO bearer access token.

Multi-role users and the schools array

In Clever API v3.x, roles such as teacher and staff can be scoped to specific schools through the roles object.

Condensed example for a user with both teacher and staff roles:

{
  "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 means:

• a user may be a teacher at one school but not another
• a user may be staff or admin at multiple schools
• your app may need to understand school context differently for each role

Exceptions and considerations

• district_admin is district-wide and does not use a schools array
• for students and teachers, the schools array lists the schools associated with the user’s sections
• students and teachers also include a school field
  • if your app needs a primary school for those users, use school, not schools
• staff users do not have a primary school field in the same way students and teachers do
  • use the schools array for staff role school context

For more context on primary school assignments, see this Help Center article.

Implementation recommendations

1. Assume multiple roles when applicable

Users with a student or contact role cannot hold multiple roles in Clever. For other user types, assume multiple roles are possible and inspect all available roles before deciding how to handle the user.

2. Choose a role-handling strategy

Two common approaches work well:

• Option 1: Consolidate roles into one account

  • Treat all roles as part of one user account
  • Adjust the experience dynamically based on available roles
  • This works well for apps with unified views or role-aware permissions

• Option 2: Create role-specific accounts or views

  • Separate experiences by role
  • Let users switch between role contexts in the UI
  • This works well when teacher and admin workflows are fundamentally different

3. Map permissions carefully

Decide how Clever roles map to your own permission model.

For example, you may choose to:

• grant access based on the most privileged role
• let district admins manage role-based permissions inside your app

4. Make the UI clear

If your app supports multiple role contexts, either:

• combine the relevant access into one experience, or
• provide a clear role switcher

For example:

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

5. Handle SSO role context gracefully

Clever SSO identifies the logged-in user as a type on the /me endpoint, but it does not tell you which role context the user wants at login.

Your app is responsible for determining which roles are available and routing the user appropriately.

FAQs

Do users have a primary role?

No. The roles object includes all roles the user holds. Clever v3.x does not define a primary role.

Should I consolidate or separate accounts by role?

It depends on your app. Many apps consolidate roles for simplicity, but role-specific experiences may work better when workflows differ significantly.

What if I’m upgrading from v2.x?

You will likely need to refactor any logic that assumes a user has only one role. You may also need to update permission handling and user-ID assumptions for teacher, staff, and district admin users.

Can contacts have multiple roles?

Contacts receive a multi-role user ID like other user types, but contacts cannot actually be assigned multiple roles in a district.

For example, if a teacher is also a contact in the district, Clever returns two separate records:

• one teacher record
• one contact record

Each record has its own Clever user ID.