Clever Secure Sync - Overview

Use this page to design your district onboarding flow, store district access correctly, and choose a strategy for matching Clever data to accounts in your product.

How district onboarding works

When a school or district decides to provision and maintain records in your application through Clever, you need a way to:

1. identify the district connection
2. retrieve or store the district-app token
3. associate that district with the correct account in your product
4. match existing records when needed

There is no one onboarding model that works for every product. The guidance on this page covers the approaches that work well for many Clever integrations and the tradeoffs to consider before you choose one.

Get district-app tokens

Every time a district authorizes your application, Clever creates a district-app token that stores the details of that authorization. A token is a string such as 7f76343d50b9e956138169e8cbb4630bb887b18.

To sync data automatically for a district, store either the district’s token or the Clever district ID.

Manual access

After you sign in to Clever, click a district and view or copy the token from the district’s overview.

Query tokens programmatically

Using your app’s client ID and secret, you can query the GET https://clever.com/oauth/tokens endpoint, which returns a list of every token granted to your application.

For programmatic import of district tokens, Clever recommends this approach.

To retrieve a district-specific token, add the district parameter:

GET https://clever.com/oauth/tokens?district=<id>

Associate records with district-app tokens

Once you receive a district token, decide whether you want to store the district ID, the token itself, or both.

Store district IDs

Clever gives every record a globally unique ID, including the district. If you tie your top-level object to the Clever district ID, you can identify which token on /oauth/tokens you need to sync the data.

This approach lets your system continue syncing automatically even if the token string changes, because /oauth/tokens always returns the active token.

Store tokens

If you retrieve tokens manually, or if you do not want to refresh tokens every time you sync data for a district, you can store the district-app token directly.

Do not store individual SSO bearer tokens. If your process depends on manually updating district tokens, note that during certification. If a token is compromised, Clever coordinates token rotation to reduce customer impact.

Choose a self-serve onboarding strategy

Before you design your onboarding flow, review how much of your existing process depends on manual entry, internal operations, or customer setup.

These strategies can reduce manual work for your team while still helping customers connect the correct Clever district to the correct account in your product.

Match on MDR number

Clever supports district and school MDR numbers. You can find this value in the /v3.0/districts and /v3.0/districts/<id> responses. If your product already stores MDR numbers, you can use this field to match Clever districts to internal organizations.

• Pros
  • Fields are populated automatically by Clever.
  • Clever can update them as needed.
• Cons
  • MDR numbers are not available for all districts.
  • This approach requires access to the MDR database.
• Development tasks
  • Add MDR number to your organizations.
  • Compare your database value to district.mdr_number.
• Edge cases
  • Missing MDR numbers
  • Clever districts that are not actual districts, such as single-school signups, and therefore do not have MDR numbers

Match using Clever Single Sign-On

When a user logs in to your application through Clever, the district ID is included in the /me response. You can use information from that user to match them to an organization in your database.

• Pros
  • Any shared user in the district can log in and provide the district ID.
• Cons
  • Users might try to log in before district data is ready.
• Development tasks
  • Build a matching algorithm that connects the user’s district ID to the correct organization in your product.
• Edge cases
  • Multiple users trying to follow this flow at the same time to associate the district ID

Match using a Log in with Clever button

You can use the optional state parameter on a Log in with Clever ("LIWC") link to connect a district to the correct organization in your product.

Here is a common flow:

1. Embed the LIWC link in your admin dashboard or send it to the admin by email. The link format is https://clever.com/oauth/authorize?client_id=<client id>&redirect_uri=<redirect uri>&response=code&state=<state input>.
   • The redirect URI can be different from your primary redirect URI.
   • You should still use the state parameter to prevent CSRF.
2. After the user logs in, Clever sends them to the redirect URI with the code and the same state value you provided.
3. After the OAuth flow is complete, use the district ID from the user and the state value to identify which organization the user is trying to connect.

• Pros
  • Any user can follow this link to provide a district ID, but you can better control which users see the flow.
• Cons
  • Users might try to log in before district data is ready.
  • You may need to launch and then unlaunch the connection.
• Development tasks
  • Process the state parameter and optionally use a separate redirect URI for matching.
• Edge cases
  • Multiple users trying to follow this flow at the same time to associate a district ID

Let admins choose from a list

In this flow, an admin selects the district from a list of unmatched districts shared with your application. You can also add search or ranking to make likely matches easier to find.

• Pros
  • Can be fully self-serve
  • Can also reduce work for your internal team
• Cons
  • Still requires manual input
  • Adds edge cases around selecting the correct account
• Development tasks
  • Build a filtering or selection UI
• Edge cases
  • District names are not always unique
  • Users can choose the wrong account, so you need a way to correct mismatches
  • The admin in your product may not be the same person as the Clever district administrator

Match on email patterns

Compare synced email addresses or email domains to the organizations in your product.

• Pros
  • Can be fully automated
• Cons
  • Has many opportunities for incorrect matches
• Development tasks
  • Compare synced API data to organization data in your database
• Edge cases
  • Districts with multiple Clever accounts

Match existing records

When you convert an existing customer to a Clever sync, you may need to match data already in your product to data coming from Clever.

You can do this in one of two ways:

• build your own matching process
• use Clever’s Matchmaker tool to bootstrap matching for students, teachers, sections, and schools

🚧

Check your work

No matching strategy will be 100% successful. Even when data is clean, some records will fail to match or produce questionable matches. Make sure your process supports review of failed and uncertain matches.

Use a matching algorithm

Identify fields in your existing data that are both unique and present in Clever data. Match on those fields and store Clever IDs so future updates stay tied to the correct resources.

Schools

Many developers find school matching easier to do manually, either internally or with school admin help, because it usually only needs to happen once.

Clever also provides MDR Number and NCES ID to help with school matching.

Many schools in Clever include NCES IDs, either loaded from the SIS or added by Clever on request. However, coverage is not complete, and some schools do not have a populated nces_id.

Clever also has strong coverage for mdr_number fields in U.S. school records.

Users

Students

Developers often match students using these fields, from most reliable to least reliable:

1. Primary ID numbers (sis_id, student_number)
2. Secondary ID numbers (state_id)
3. Birthdays (dob)
4. email address
5. name

Teachers

Developers often match teachers using these fields, from most reliable to least reliable:

1. email address
2. Primary ID numbers (sis_id, teacher_number)
3. Secondary ID numbers (state_id)
4. name

Staff

Developers often match staff using these fields, from most reliable to least reliable:

1. email address
2. staff_id
3. name

Multi-role users

Clever recommends creating one account for a user with multiple roles. If your product currently creates separate teacher and staff accounts, associate each existing account with the same Clever ID so the user can switch roles after login or select the intended role.

To consolidate accounts into one, iterate through each role response on the user object and match using the fields listed above for each role.

If you must keep separate accounts for each role, complete matching by role by adding the ?role parameter to the user endpoint and using the relevant matching fields. Separate accounts will still use one Clever ID for future updates.

Sections

Clever does not recommend matching existing sections to sections in Clever because unique section identifiers rarely exist in existing data sets.

If matching sections is essential to your product, start by matching on school and teacher to narrow the set of possible matches.

🚧

Name is not reliable

Clever does not recommend a fully automated name-based match because multiple students in the same district, or even the same school, can share the same name.

Optional: Use Matchmaker

You can access Matchmaker from the Clever Dashboard by clicking Matchmaker in the left navigation. Matchmaker compares district data already shared with your application against the data you upload, reducing the amount of manual matching work you need to do.

📘

Requires Clever Secure Sync

Matchmaker is only available for applications that support Clever Secure Sync because it requires access to full district records.

How Matchmaker works

1. A district authorizes your application through Clever and shares records.
2. You upload a CSV containing your existing student, teacher, admin, school, or section and enrollment records.
3. Matchmaker compares your CSV to the records shared with your application in Clever.
4. Clever emails you a CSV containing matched and unmatched records.

🚧

Matchmaker is not perfect

Matchmaker does its best to match your records, but you should always review the output before processing it.

Matchmaker also performs poorly on sample data sets, where duplicate names often increase the chance of false negatives.

Input CSV guidelines

When you create a CSV for Matchmaker, follow these guidelines. Use this example CSV as a reference.

Your file:

• must be a valid CSV file that follows RFC 4180
  • every row should contain the same number of comma-separated columns
  • values that contain commas should be enclosed in matching quotes
• must include a column header for each field
• should include as many fields as possible to improve match quality
• must include a unique internal identifier for each record
• should include exactly one record per user

If a user has multiple accounts in your product, choose one account to match. Duplicate records will not be matched.

Output CSV format

Matchmaker returns a CSV that includes all of your input fields plus additional Clever identifying fields.

• Input fields are prefixed with app, such as app.email
• Clever fields are prefixed with clever, such as clever.id
• The matchmaker_results column shows the match status

Possible values for matchmaker_results are:

• match — the record was matched
• from app, no match — the record from your application could not be matched to a Clever record
• from app, duplicate — the record from your application was a duplicate of another record in your application
• from Clever, no match — the Clever record could not be matched to a record in your application
• from Clever, duplicate — the Clever record was a duplicate of another Clever record

Once you receive the output CSV, associate the matched records in your application with the corresponding Clever ID in the clever.id column.

Privacy

Matchmaker only compares your uploaded app records against district records already shared with your application in Clever.

Matchmaker input and output CSVs are removed from Clever’s systems 30 days after upload.

Optional: Process data for accounts not on Clever

If you need to process data for an account that is not on Clever, use Clever’s AnySchool solution.

Read Clever AnySchool Quickstart Guide to learn more.