DFL-as-consumer (embed SSO + results)

DFL consumes Itera in two directions: it frames the Itera player for its fellows (embed SSO), and it reads their results back for dashboards / LMS admin / Gantt (per-tenant key). Neither direction authors content — that’s itera-mcp.

Direction 1 — embed the player (SSO)

A DFL fellow inside a dfl-learn iframe is signed in to Itera with no re-login. DFL is the federated IdP; Itera trades a verified DFL token for a fresh Itera session.

1. The DFL host posts the fellow’s DFL access token into the iframe.

2. The embed exchanges it for an Itera session:

   curl -X POST https://api.iterahq.dev/v1/embed/session \
     -H "Content-Type: application/json" \
     -d '{ "dfl_token": "<DFL access_token>", "tenant": "dfl-batch" }'

   → { "access_token", "refresh_token", "expires_in": 3600, "itera_user_id" }

3. The player sets the session (supabase.auth.setSession(...)) → fully authed, RLS-scoped Itera session for that fellow (role learner).

Same endpoint mints teacher tokens

/v1/embed/session is also how an internal DFL teacher gets an Itera token to author — the difference is a learner vs author membership. See Authentication → internal DFL teacher.

Direction 2 — read results back

DFL pulls its fellows’ activity results / progress / artifacts with a per-tenant API key for the dfl-batch tenant:

curl "https://api.iterahq.dev/v1/progress?limit=200" \
  -H "Authorization: Bearer itera_<prefix>_<secret>"

Everything is scoped to the tenant the key belongs to. Full endpoints + schemas: Reading results (itera-api) and the read-results recipe.

The AI judge (optional)

When a fellow submits a judged artifact (diagram / document / code / quiz), the player calls POST /v1/embed/judge (DFL-JWT) to grade it against the activity’s spec + rubric and gate progress on a pass. It degrades gracefully to status: "pending" (still 200) when unconfigured — see results-api.

flowchart LR
  fellow["DFL fellow<br/><small>dfl-learn iframe</small>"]
  session["/v1/embed/session<br/><small>DFL JWT → Itera session</small>"]
  player["Itera player"]
  judge["/v1/embed/judge<br/><small>grade artifact</small>"]
  results["/v1/activity-results<br/>/v1/progress<br/><small>tenant key</small>"]
  dashboards["DFL dashboards / LMS admin"]

  fellow --> session --> player --> judge
  dashboards -->|pull| results