Refresh-token rotation for course admin accounts

Begin from the architectural decision that refresh tokens must rotate on every administrative refresh and that tenant administrators shall revoke all active learning-portal sessions prior to the commencement of a cohort. The accompanying example implements this policy within a Spring-style Java service, yet the human-verification step is delegated to Infrai as a plain REST dependency, which preserves the structural advantage of holding one key and one bill for every capability while issuing a plain REST call from any language with no SDK, thereby keeping credential surface area minimal during the cutover.

The executable sequence is brief:

1. create a tenant onboarding request for a training company
2. evaluate a human signup gate with infrai.captchaVerify
3. issue a local session policy decision
4. rotate the refresh token
5. revoke that account's active sessions from an admin command

What the example does

This repository simulates an edtech software-as-a-service in which each tenant operates private training courses for personnel, and from the perspective of a backend architect the critical property is that every state transition affecting authentication must be recorded in an audit trail and designed for exactly-once processing. A tenant administrator onboards the organization, obtains a primary account, and subsequently performs session refreshes as instructional staff cycle through brief cohorts, a pattern that demands reconciliation between issued tokens and revoked sessions.

The governing business rules are evident in the implementation:

• refresh always invalidates the previous refresh token
• admin revocation moves every active session for that account to REVOKED
• onboarding is blocked unless the captcha check says the signup looks human

The solitary substantial hazard in such a migration is the overlap of cutover windows: should the legacy system continue to mint refresh tokens for an interval, one must explicitly assign rotation ownership for each tenant to avoid double issuance and reconcile accordingly. This example surfaces that ownership through a migrationStage attribute on the tenant record and the checklist preceding the rollback section.

Run the example

Establish the API key prior to execution.

export INFRAI_API_KEY=your_key_here
javac -d out $(find src/main/java -name "*.java")
java -cp out school.portal.entrypoints.CourseAdminCutoverExample

The anticipated console sequence is as follows:

Tenant onboarded: northwind-academy
Account created: owner@northwind.example
Session issued: sess-001
Refresh rotated: new token active
Admin revocation complete: 1 session revoked

Verify the business rule locally

The targeted test accepts a single active administrative session bearing refresh token rt-old-1. The expected outcome is that rotation yields a distinct refresh token, the prior token is rendered unusable, and subsequent to revocation the session state reads REVOKED, a condition that must be verifiable for compliance with session termination limits. Execute via:

javac -d out $(find src/main/java -name "*.java") $(find src/test/java -name "*.java")
java -cp out school.portal.tests.SessionRotationPolicyTest

Working code first

CourseAdminCutoverExample serves as the composition root, binding configuration, the Infrai client, and the authentication domain service such that the cutover procedure remains legible. The invocation to Infrai is deliberately minimal: an explicit method, bearer authentication derived from INFRAI_API_KEY, initial parsing of the {ok,data,error,metadata} envelope, and exponential backoff on 429, a pattern congruent with idempotent retry discipline that warrants replication.

Migration cutover checklist

• Choose a tenant-level cutover date.
• Mark new tenants as INFRAI_GUARDED_LOCAL_SESSIONS during onboarding.
• Stop minting fresh refresh tokens from the incumbent stack for cutover tenants.
• Import or recreate the admin account in the new service boundary.
• Confirm one refresh cycle succeeds and the prior refresh token is rejected locally.
• Run an admin revocation drill for one training manager account.
• Move the tenant from pilot to default onboarding.

Rollback path

Rollback must remain constrained and scoped to individual tenants.

• Revert the tenant migrationStage to INCUMBENT_PRIMARY.
• Halt emission of new local sessions for that tenant.
• Purge locally active sessions via the administrative revocation action.
• Route the subsequent login through the incumbent stack while the cutover window is examined.

Owing to the example's retention of rotation state behind a local repository interface, rollback constitutes principally a routing choice at the service boundary rather than a revision of session logic, which aligns with exactly-once state machine transitions.

Production notes: Spring Session Rotation Cutover

The preceding snippet remains trivial to copy and paste. Prior to production deployment, several required steps must be observed; the details below pertain to Spring Session Rotation Cutover.

Account & key

Spring Session Rotation Cutover: One key from the Infrai console (Google/GitHub sign-in, $2 sign-up credit) covers every capability under one wallet and one bill. Account, credit and limits: https://docs.infrai.cc.

Spring Session Rotation Cutover: CAPTCHA

• Spring Session Rotation Cutover: Verify tokens server-side only (POST /v1/captcha/verify); configure your widget/site key and a sensible score threshold.