Clever Single Sign-On Quickstart Guide

❗️

Clever Complete Agreement Required

This feature is included with a Clever Complete subscription. Sign up here or email your Application Success Manager to learn more.

Table of Contents

Overview
Steps to Getting Started with Clever Single Sign-On
Steps to Getting a Clever Single Sign-On Integration Running

---

Clever Single Sign-On (SSO)

Welcome to the Clever SSO Quickstart Guide! Clever SSO uses a standard OAuth 2.0 flow (Authorization Code Grant) to securely authenticate students, teachers, and staff without requiring them to remember another username and password.

Clever can serve as an identity provider for your application, allowing teachers, students, staff, and district admins to seamlessly log in to your application without needing to manage additional credentials. With Clever SSO, end-users need only log in to Clever in order to access a plethora of learning and education resources.

This guide will walk you through setting up your redirect URIs, generating a "Log in with Clever" button, and exchanging an authorization code for user data.

For more details on the process, see our additional Clever Single Sign-On guides in the left side menu.

📘

Already familiar with SSO?

Please don't skip this section if you are just getting started with Clever SSO! You will need to familiarize yourself with how Clever end-users use SSO and the different types of SSO integrations you can build.

How does Clever SSO work for end-users?

Clever SSO works through three main workflows. Listed below are high-level descriptions. You can find more detailed implementation notes in later sections.

🚧

SSO through the Clever Portal is strongly recommended

A large majority of Clever end users use the Clever Portal for SSO into their applications. Clever strongly recommends that your integration should support at least SSO via the Clever Portal.

SSO through a Log in with Clever button is optional.

1. SSO through the Clever Portal

The Clever Portal serves as a launchpad for Clever users where they can quickly access their learning/education resources through a collection of icons. If you choose to build an SSO integration, your application would be represented as an icon on the Clever Portal once a connection has been established with a district or user. To learn more about the Clever Portal, check out this Help Center article.

2. SSO through an Authorization Link

An Authorization Link can be tied to a "Log in with Clever" (LIWC) button on your application's login page. If users are accustomed to navigating directly to your site to log in, it is helpful to offer a LIWC button the same way you might provide authentication options for Google or other 3rd party social authentication offerings. An example authorization link is:

<https://clever.com/oauth/authorize?response_type=code&redirect_uri=&client_id=>

3. SSO through an Instant Login Link

Some districts prefer not to use the Clever Portal, but still want to use SSO 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. An example Instant Login link is:

<https://clever.com/oauth/instant-login?client_id=&district_id=>

🚧

Clever Library and Instant Login Links

Instant Login Links do not work for the Clever Library integration type.

📘

Field Access by Access Tier

Be sure to check out https://clever.com/schema to see field-level access for each integration type.

What kind of SSO technologies does Clever support?

• OAuth 2.0
• OpenID Connect (OIDC)
• SAML

Both Clever SSO and Clever Library use OAuth 2.0 authorization code grant flow and/or OIDC to provide user-level data. If you are unfamiliar with these, see OAuth and OIDC Overview before proceeding.

While SAML is not recommended due to more lift for district administrators to set up, it is an alternative approach that can be handy in a pinch. You can learn more about implementing a SAML connection with Clever by reading SAML Overview.

🚧

SAML is not supported for Clever Library

Because Clever SAML connections require district-level configuration, the teacher-facing nature of Clever's Library integration is incompatible.

🚧

OIDC is not supported for Clever Library

At this time, OIDC is not supported for the Clever Library integration. You will need to use the /userinfo endpoint as opposed to the ID token. please reach out to our support team in our Help Center chat for more information.

---

Steps to Getting Started with Clever Single Sign-On:

Prerequisites

Before you begin, ensure you have:

• A Clever Developer Account: Sign up at apps.clever.com/signup
• Your Client Credentials: Find your Client ID and Client Secret in your Clever App Dashboard under Settings.

---

Steps to Getting a Clever Single Sign-On Integration Running:

Step 1: Configure Your Redirect URIs

When a user successfully authenticates with Clever, Clever will redirect their browser back to your application with a temporary authorization code.

1. Log in to your Clever App Dashboard.
   • Navigate to Settings > Redirect URIs.
2. Add the exact URL where your backend will handle the OAuth callback (e.g., https://localhost:3000/auth/clever/callback for local development, or https://yourapp.com/auth/clever/callback for production).

🚧

Redirect URIs must be registered and will be validated!

Clever strictly validates the redirect URI. It must match exactly what you send in your API requests, including trailing slashes.

Step 2: Create the "Log in with Clever" Request

To start the SSO flow, you need to send the user to Clever's authorization endpoint. This is typically triggered when the user clicks the icon for your app from their Clever Portal or when the user clicks a "Log in with Clever" button on your site.

Redirect the user's browser to the following URL, replacing the placeholder values with your own:

HTTP  
<https://clever.com/oauth/authorize?response_type=code&redirect_uri=>\<YOUR_REDIRECT_URI>&client_id=\<YOUR_CLIENT_ID>

What happens next?

The user will see the Clever login screen. Once they enter their Clever credentials (or if they are already logged into the Clever Portal), Clever will immediately redirect them back to your redirect_uri with a code attached to the URL:

https://yourapp.com/auth/clever/callback?code=1234567890abcdef

Step 3: Exchange the Code for an Access Token

Now that your server has the authorization code, you need to securely exchange it for an access_token. This step must happen on your backend, as it requires your Client Secret.

Make a POST request to Clever's token endpoint.

cURL Example:

Bash  
curl -X POST "<https://clever.com/oauth/tokens">  
     -d '{  
           "code": "1234567890abcdef",  
           "grant_type": "authorization_code",  
           "redirect_uri": "\<YOUR_REDIRECT_URI>"  
         }'  
     -H "Content-Type: application/json"  
     -H "Authorization: Basic \<BASE64_ENCODED_CLIENT_ID:CLIENT_SECRET>"

🚧

The Authorization header requires your Client ID and Client Secret joined by a colon and Base64 encoded.

Expected JSON Response:

JSON  
{  
  "access_token": "token_abc123..."  
}

Step 4: Identify the User

You now have a user-specific access token! Use this token to hit the /v3.0/me endpoint to find out exactly who just logged in.

cURL Example:

Bash  
curl -X GET "<https://api.clever.com/v3.0/me">  
     -H "Authorization: Bearer token_abc123..."

Expected JSON Response:

JSON  
{  
  "data": {  
    "id": "5f3e4b1c...",  
    "district": "5de12345...",  
    "type": "student",  
    "name": {  
      "first": "John",  
      "last": "Doe"  
    }  
  },  
  "links": [...]  
}

You can now use the id from this response to look up the user in your own database and log them into a session!

What's Next?

Map Users to Your Database: Use the /me endpoint to identify the user, and if you need their full roster data, use their id to query the Secure Sync API (/v3.0/users/{id}).

Test with Sandbox Users: Use the "Custom Test User" tool in your Clever Dashboard to simulate logins for different user types.