People & Access
SSO Launch (LMS)
Put a student inside GroutApp or GroutCode from a button in your LMS, no one-time code.
Your server mints a one-time launch token for a known student or teacher; the browser is sent to a portal page that hands the token to the desktop app; the app trades it for a normal session.
LMS Grout API Portal Desktop app
│ POST /v1/sso/tokens ───────►│ │ │
│ ◄── launch_url, token ──────│ │ │
│ 302 student ────────────────┼─────────────────────────────►│ /sso/launch?lt=…&app=… │
│ │ │ opens groutcodeapp://sso │
│ │◄── POST /api/sso/exchange ───┼──────────────────────────│
│ │──► session + license ────────┼─────────────────────────►│Mint a token#
curl -X POST $API/sso/tokens -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{
"email": "[email protected]",
"app": "groutcode",
"redirect": "exam:ex_9f3…",
"ttl_seconds": 120
}'{ "success": true, "data": {
"launch_token": "lt_…", "expires_at": "2026-09-14T10:02:00.000Z", "app": "groutcode",
"launch_url": "https://portal.grout.app/sso/launch?lt=lt_…&app=groutcode",
"user": { "id": "u_…", "email": "[email protected]", "user_type": "institution_student" }
} }| Field | Notes |
|---|---|
email | Login email of an active student, faculty member or admin in your institution. |
app | groutapp (default), groutcode or groutfilm. |
redirect | Free text the app receives after sign-in, e.g. exam:<id>. |
ttl_seconds | 30–300. Tokens are single-use. |
Redirect the user's browser to launch_url — mint per click, never cache.
What the user sees#
The portal page shows "Opening GroutCode…" and immediately triggers the app's deep link. If the app is not installed, the page offers a download link and asks them to click the LMS button again afterwards.
Behind the scenes#
The desktop app calls POST /api/sso/exchange with the token (no API key involved; the token is the credential). The exchange returns the same payload as a normal sign-in: session token, license, device seat. Every issued token is written to the institution audit log with your key id.
Errors#
| Status | error | Why |
|---|---|---|
| 404 | user_not_found | No such login email in your institution, or not a student/faculty/admin |
| 409 | user_inactive | Account suspended, banned or inactive |
| 401 | LAUNCH_TOKEN_INVALID | (on exchange) token expired, reused or unknown |
Events#
None on mint; the resulting sign-in produces license.device_registered when a new device seat is created.