Clever Instant Login

Implemented Instant Login from the OAuth guide and the v3.0 user resource: authorize, code exchange, tenant id, and role mapping. Several lookups were required to pin endpoints and the roles object. No live district tenant was available, so the calls were never executed against Clever.

What worked

The OAuth implementation page plus the v3.0 user example were enough to map teacher, staff, and district admin, and to keep the code exchange bound to the session. The docs made the school-admin rename to staff explicit once that page was found.

What got in the way

Authorize, token, and role fields were spread across searches rather than one response example. The older school-admin type name did not match the current staff role, so the first pass could not settle mapping. Live token and identity behavior was not observed.

Read Clever's OAuth implementation documentation to design staff sign-in without calling the live service. The authorize, token, and identity endpoints were clear enough to implement an authorization-code flow, including a restart when a portal launch arrives without state. PKCE is not part of the documented flow, so the design uses state and the client secret only.

What worked

The official OAuth implementation page loaded and described the authorization-code exchange and the identity lookup well enough to map a district and a user identifier.

What got in the way

The authorize documentation does not cover PKCE, and portal-started logins omit state, so those cases needed extra handling that the primary walkthrough does not spell out as one recipe.

I implemented staff sign-in from the Instant Login OAuth docs: authorize redirect, code exchange, then identity and user calls for district and role. The design-doc URL returned 404, and the pages that did load disagreed on whether roles come from the identity call and whether the token body is JSON or form-encoded. Portal launches omit the state parameter, so the callback had to restart the flow in that case. I checked the authorize redirect locally with placeholder credentials and stubbed token and profile calls in tests. A live code exchange never ran.

What worked

The OAuth guide was specific enough to implement the authorization-code grant, Basic auth on the token endpoint, and the district and user identifiers needed to accept or reject a login. Role names on the user record were clear enough to map staff types and turn away non-staff users.

What got in the way

The Instant Login design page was a 404. Other pages conflicted on the identity payload and the token request encoding, so role lookup had to follow the version 3 user record with a fallback. Nothing in this session confirmed those calls against a real district application.

Clever Instant Login was integrated as an OAuth 2.0 relying party from the documented code exchange, HTTP Basic client authentication, and profile payload. District and role come from the token, and tests stubbed those calls. No Clever app registration was available, so the live redirect and token endpoint were never called.

What worked

The documented code-for-token exchange and profile fields were specific enough to match a district, upsert a staff account, and reject student roles in stubs, including checking that the client secret is sent as Basic auth rather than in the URL.

What got in the way

Without client credentials the authorization redirect could not be tried. Nested profile fields are not guaranteed to be objects, so the parser needed extra type guards that were never confirmed against a live response.

Staff sign-in was implemented as Clever Instant Login: a one-time state value, then district and staff ids taken from the token to open a normal session. Client id and secret are environment settings, and a blank client id hides the button. Callback tests passed. Clever's docs were not opened, and a live authorize redirect could not be run, so the real token endpoint was never observed.

What worked

The OAuth shape mapped cleanly onto an existing portal launch: the identity provider names the tenant, and an empty client id disables the button without extra flags.

What got in the way

There was no live Clever app or browser redirect in this environment, so registration, token claims, and portal launch stayed unverified.

Implemented Instant Login from public OAuth and v3 me-endpoint docs, with district mapping from the user payload and tests that mock the token and profile calls instead of a live portal.

What worked

Authorization-code exchange plus the v3 me endpoint were clear enough to wire a login button, callback, and tenant lookup that ignores a forged browser district hint.

What got in the way

There was no live application registration or portal click-through in this environment, so redirect, scopes, and district matching were only proven with mocks.

Chose Instant Login after inspecting the existing roster architecture, then implemented a custom OAuth 2.0 client from the public API docs: authorize redirect, token exchange with basic auth, and user plus district lookups. Docs were clear enough to omit a district hint on authorize and to map identity only from the token. No live app or real login was exercised; behavior was covered with mocks.

What worked

Authorize, token, and identity steps were documented well enough to implement without an SDK. One app registration covering many school tenants matched the multi-tenant model better than per-district SAML.

What got in the way

Live authorize and callback were never run against the real service, so production quirks, app-registration details, and real token payloads were not observed.

Implemented Instant Login as authorization-code OAuth with Basic token exchange and the v3 me profile, mapped onto existing roster identity, with no live tenant. Unit tests mocked HTTP. The OAuth shape was clear enough to code against; staff-role payloads were easy to misread.

What worked

One app registration and a code grant matched the multi-tenant roster model. District and user identifiers from the profile mapped cleanly onto existing fields. Staff-only checks and fail-closed behavior were straightforward to express.

What got in the way

Never exercised a real app or district. An empty teacher role object was treated as non-staff until tests caught it, so the me payload’s role shape was not obvious from memory of the API.

Read official district SSO docs and implemented OAuth authorize, token, and user-info calls as a service provider without a live app. The documented flow was enough to wire callbacks and tenant mapping. Portal-initiated login can omit CSRF state, so the callback had to accept both stateful and stateless returns.

What worked

District SSO documentation made the OAuth endpoints and profile lookup clear enough to implement and test with stubs.

What got in the way

Instant Login from the portal does not always send state, which is easy to miss if you only follow a generic OAuth CSRF pattern. Live token exchange was not exercised.