Skip to main content

Simple Oneroster client for user management

Project description

Oneroster Python Client

This library is in beta, and changes often. Use at your own risk.

This library facilitates easy access to the user database from Clever or Classlink.
The connectors provide single-method calls that will return users (students, teachers or both) from the provider of your choice, based on class, course, or school membership without the need for paging and response handling. Additional documentation to come.

For the time being, this library only returns users for differente classes, courses and schools - it was designed for this purpose as integrated into a sync process. Additional options for fetching other data types will hopefully come down the line.

For details on the development of this library, visit

Contact Danimae Vossen ( for inquiries

Quick Start

*Note: a full version of this code can be found here

pip install oneroster

Begin by installing the oneroster dependency as above (home is here). The constructor takes more than 3 arguments, but 3 is all you need to instantiate it. These arguments are:

  1. host name - this should come from your SIS dashboard (classlink here). It may look different for different providers
  2. client_id - also from SIS dashboard
  3. client_secret - also from SIS dashboard

Import and instantiate the connector (Classlink) as shown.

import oneroster
from pprint import pprint						# optional

connector = oneroster.ClasslinkConnector(

For a first try, you can call get_users, giving a single argument: 'students'. This will return a list of all the students in the system.

user_list = connector.get_users(user_filter='students')

print(str(len(user_list)) + " students in total")

The connector queries are made up of 3 main arguments:

user_filter - this 'filter's the kind of user requested. The options are: students, teachers, and users. students and teachers work for any query, but users is only available when getting a full list (e.g.: /ims/oneroster/v1p1/users)

group_filter - the word 'group filter' is chosen to represent how users might be grouped. This can be any of: classes, courses, schools. This is equivalent of making an api call like: /ims/oneroster/v1p1/classes/class_id/{user_filter}

group_name - the 'group name' indicates which class, course or school we want to target. This might be the name or id of a class. The final query with the group and user filters looks like this: /ims/oneroster/v1p1/{group_filter}/{group_name}/{user_filter}

For example: /ims/oneroster/v1p1/classes/31763/students

The following snippets should help to illustrate this. Consider the simple case of getting all students for classes named ELA (6A ELA):

class_name = "ELA 6 (6A ELA)"
ela_users = connector.get_users(user_filter='students',

print(str(len(ela_users)) + " users found for ELA 6")

Alternatively, we can query the same class using it's sourcedId. This second case may return less results, because an id corresponds to a specific section, whereas the classname gets all sections sharing that name.

class_id = "31763"
ela_users = connector.get_users(user_filter='students',

print(str(len(ela_users)) + " users found for ELA 6 (1 section)")

We can expand the option of "match groups by" by setting the connector option. The default is ['sourcedId', 'name', 'title'], which means that the group name you enter will be compared against these three fields for matches. This means you can make queries using any of those 3 fields. For example, we can query for "Classlink HS" and school with id 7 (the middle school), and both will return results. You are free to set the match_groups_by field to any of the fields in your target object (a class, course, or school)

hschool_users = connector.get_users(user_filter='students',
                                    group_name='Classlink HS')

mschool_users = connector.get_users(user_filter='students',

print(str(len(hschool_users)) + " high school students returned")
print(str(len(mschool_users)) + " middle school students returned")

You can change the matcher by setting the class level property or by passing it with get_users. As an example, let's say we want to get the number of students with classes in room 302. We can look at the available JSON properties from the api standard, and see that 'location' represents a room. We can pass this expicitly in the call as shown. Note that for the moment, only string type matchers are allowed. The 'grades' field is represented by a list like ['11'] - and so it is an invalid matcher. Extended matching functionality will come in a future release.

connector.match_groups_by = ['sourcedId', 'name', 'title', 'location']
connector.match_groups_by = 'location'
r302_users = connector.get_users(user_filter='students',

print(str(len(r302_users)) + " students with classes in room 302")

When run, the above snippets result in the following output:

139 students in total.  First result:

{'agents': [],
 'dateLastModified': '2019-03-01T18:14:45.000Z',
 'email': '',
 'enabledUser': 'true',
 'familyName': 'FLORES',
 'givenName': 'BILLY',
 'grades': ['11'],
 'identifier': '17580',
 'middleName': 'DASEAN',
 'orgs': [{'href': '',
           'sourcedId': '2',
           'type': 'org'}],
 'password': '',
 'phone': '',
 'role': 'student',
 'sms': '',
 'sourcedId': '18125',
 'status': 'active',
 'userIds': [{'identifier': '18125', 'type': 'FED'}],
 'username': 'billy.flores'}

7 users found for ELA 6
3 users found for ELA 6 (1 section)
38 high school students returned
54 middle school students returned
13 students with classes in room 302

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for oneroster, version 0.0.10
Filename, size File type Python version Upload date Hashes
Filename, size oneroster-0.0.10-py2.py3-none-any.whl (16.7 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size oneroster-0.0.10.tar.gz (13.1 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page