Clever Developer Docs

Classroom vs District Integrations

This chart outlines the key differences between a Classroom and District integration. When you sign up for a dev app, your app will have Classroom scopes by default. Please reach out to application-interest@clever.com to upgrade your dev app to rostering scopes.

Classroom Rostering and SSO

What is the classroom integration experience?

When a teacher clicks on a new app in the Clever Library, or via the ‘Sign Up with Clever’ button, the teacher is prompted with a consent screen to authorize Clever sharing their section (class) data with the app. Once authorized, Clever redirects the teacher to your app and you facilitate the OAuth Single Sign-On flow, using API calls to query for the user’s identity and classroom information. The teacher’s account is provisioned immediately, and the teacher is logged in to a free or freemium experience with their section and student data populated. The app is added to the Clever Portal for the teacher and their shared students, so those students can also log in to the app.

There are two entry points into your application that facilitate the teacher sign up process:

  1. Teachers who find you through the Clever Library and click “Install".
  2. Teachers who click “Sign Up with Clever” button on your website’s teacher signup page.

What data is shared?

If the teacher consents, your application will be authorized to access the following limited set of data fields for class information only belonging to that teacher. You'll use this data to automatically create user accounts and set up classes to make the signup experience as smooth and seamless as possible.

Teacher object data

  • Clever ID - globally unique and stable ID for each user, created by Clever
  • Name (first, middle, last)
  • Email

Teacher’s shared sections, as primary or co-teacher

  • Clever ID
  • Name
  • Section_number
  • Teachers
  • Students
  • Subject (normalized to a set of possible values)*
  • Grade (if available from the SIS)*

Student object data in those sections

  • Clever ID (this is not sid_id or student_number; it’s a GUID generated by Clever)
  • Name
  • Grade (if available from the SIS)*

Sandbox Data

Even though your dev app comes with a pre-populated, pre-created sandbox district, it’s important that you test with a demo teacher from a district in Clever that is not connected at the district level to your development app. This will provide a representative test of a signup experience from a Clever teacher who is not currently shared by a school or district.

Also, note that school and district administrators do not have permissions to log in to your application via Clever Library, as a teacher is limited to only sharing his/her classroom data. Administrators must be shared at the district level to access an application.

*Normalized Fields

Clever normalizes certain fields to a defined set of possible values:

Subject: ["english/language arts","math","science","social studies","language","homeroom/advisory", "interventions/online learning","technology and engineering","PE and health","arts and music","other"]

Grade: [ "1", … ,"12", "PreKindergarten","Kindergarten","PostGraduate","Other"]

Accessing the District and School Data with Classroom scopes

You will not be able to access District or School level data with your default Classroom scopes. In order to gain access, please reach out to application-interest@clever.com

District Rostering and SSO

Secure Sync allows you to access information about users and provision accounts in advance, so you can use that time to improve your core product. If you need access to Secure Sync, reach out to application-interest@clever.com.

What is the district experience?

District administrators will be able to search for your application in the district dashboard and then scope access to all users within the district. With a district-level integration, your application can be scoped to all users who require access within a district. Once the data is shared, all scoped users data will be available via the district-app token so you will be able to roster and provision accounts at scale.

There are three ways a user can log in to your application using Instant Login: the Clever Portal, Instant Login links, and Log in with Clever buttons. Your integration should be able to handle logins from any of these sources.

  1. Clever Portal - Many districts use the Clever Portal as the primary launch point into their applications.

  2. Instant Login Links - Some districts prefer not to use the Clever Portal, but still want to use Instant Login to access their applications. To support this, Clever built Instant Login links which are links that can be embedded anywhere and are used to log a district's users in to a specific application through Instant Login.

  3. Log In With Clever - Users will also often attempt to log in from an application's site directly, not using any portal. To allow users to use Instant Login to authenticate, you can embed a "Log in with Clever" (LIWC) button on your website.

What data is shared?

Secure Sync gives full access to roster information - student-teacher associations and classroom data with OAuth tokens you can retrieve from your App Dashboard or via our API. Upgrading to District Certification allows you to access the entirety of the Data API, our matchmaking tools, Data Browser and more. Our schema outlines the full list of available fields in Clever.

Sandbox Data

When your development application is first created, we'll automatically connect a sandbox district and populate it with realistic sample data, so you can test your integration. Your sandbox district will be visible in the Districts Overview page of your dashboard.

Once you receive Secure Sync access, your default sandbox district should include:

  • 239 schools
  • 8412 or more teachers
  • 56635 or more students
  • 25843 or more sections
  • 460,000 or more enrollments
  • 6 school admins

Classroom vs District Integrations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.