Federation

Federation is the contract between a hub and its spokes. It comes in three modes — pick the one that matches your relationship with each spoke.

Mode: content

The hub publishes versioned course families. Spokes pull them on demand and serve them to their own users. Each spoke owns its own users, grades, and certificates.

Use content mode when:

• Your spokes are independent organisations (resellers, customer sites, regional partners) that share course material but not learners.
• You want one place to author and version courses, but each spoke administers its own learners.
• Your reporting needs are per-spoke, not cross-spoke.

What flows from hub to spoke: the course (activities, resources, settings, structure). Not learners, not enrolments, not grades — those stay where they were made.

Mode: identity

Users sign in once at the hub. The spoke recognises them via a projected user record and lets them through without a second login.

Use identity mode when:

• You want unified identity across all your spokes (single login, one password, one place to revoke access).
• You report on cross-spoke activity (a learner's progress across multiple spokes).
• Your spokes are different facets of the same organisation, not separate ones.

What flows from spoke to hub: a projected user record (email, display name, role). The spoke is still where the user does things; the hub is just the source of truth for who they are.

Mode: both

Content and identity. The hub publishes courses, owns identity, and learns about activity across the federation. The spokes consume both flows.

Use both when you want centralised authoring and unified identity in the same federation. Most production deployments end up here once they're past pilot.

Switching modes

Mode is a federation-wide setting (not per-spoke). Changing it ripples to every Moodle in the federation via the local_nucleuscommon_set_federation_mode web service. Switching from content → identity doesn't move existing users; it just enables the projection going forward. Switching the other way doesn't remove projected users either.

TIP

You can switch mode any time via PATCH /api/federations/:id. The change takes effect on the next user action that triggers the relevant flow.

What's not federated

A few things stay strictly per-spoke regardless of mode:

• Theme + branding
• Site-level admin settings (mail config, plugins, etc.)
• Local courses created on the spoke (anything not pulled from the hub)
• Activity completion records and grades — even in identity mode
• Files uploaded to per-spoke courses

The federation runs on top of an otherwise-vanilla Moodle. Switching it off should leave each spoke working as a normal standalone site.