Wire up your integrations

You have an admin seat and you have been asked to connect First Six to the university's systems. This guide is the running order. Each step links to the reference page with the full contract; what this page adds is the sequence, the dependencies between the pieces, and the parts that are not yours to do.

The whole integration surface is deliberately small. First Six is not an LMS and not a student record system: it reads a roster, it emits events about help requests, and it renders content your staff author. There is no bulk read API for student data, by design.

About 2 hours of hands-on work, spread across the two weeks before launch.

The order, and why it is this order

Each step unblocks the next, so working out of order wastes time:

1. SSO first. Nobody, including you, can do anything else properly until staff can sign in as themselves. Staff sign-in is SSO-only.
2. Then the roster (SIS). Students must exist before they can be put in a cohort, and cohorts must exist before content targets them.
3. Then the outbound integrations (webhooks, help-desk, crisis alerts). These carry events about students, so they only produce anything once there are students.
4. Event feeds last. They are additive and safe to add at any point, so they never need to block a launch.

Walk through it

1. Register First Six in your identity provider

   Create an OIDC app registration in Entra, Okta, or Google Workspace. You own this step entirely: it mints the client ID and client secret. Register the redirect URI exactly as First Six gives it to you, in the form https://<your-console-host>/auth/sso/<your-slug>/callback. A mismatch here is the single most common sign-in failure, and the error your IdP returns is usually unhelpful about it.

   Send the client ID and the discovery URL to First Six, and send the client secret by a channel that is not email. Full flow, including the claims we read: the OIDC flow.

2. Test SSO with a real account, not a test one

   Once First Six confirms the config is in, sign in with a genuine staff account from your directory. Some providers send a UPN rather than an email address, and only a real login surfaces that. SSO links a sign-in to a staff row that already exists; it does not create accounts, so invite the staff member first or the link has nothing to attach to.

3. Get your SIS secret from the console

   In the console, go to Settings → Integrations → Connect your student system. Generate the secret there. It is shown once: store it in your secret manager immediately, because it is stored as a hash and cannot be read back.

   You can rotate or revoke it yourself from the same screen. Rotating invalidates the previous value straight away, so schedule it for a window where your feed is not mid-run.

4. Push a roster with dry_run first

   POST /api/sis/sync with Authorization: Bearer <your secret>, the target cohort_id, and your student rows. Send "dry_run": true on the first run. You get back a validation report (would_create, would_update, unknown_program_codes, unknown_campuses, duplicate_emails, plus per-row issues) and nothing is written.

   Treat that report as the pre-go-live roster check. Unknown programme codes and campuses are the usual finding, and both are fixed on your side by matching the values the console already holds, not by inventing new ones. Full body shape: the SIS endpoint.

5. If you run block or term teaching, push the term calendar too

   Universities on a rolling term model (six-week blocks and similar) also POST /api/sis/enrolments, which accepts three optional sections in one body: terms (the calendar), units (the unit catalogue, including each unit's lms_url), and enrolments (per-term, per-unit rows). Same bearer auth. dry_run writes nothing at all here: the enrolment rows are validated and reported, and the terms and units sections are skipped and reported rather than applied.

   Push this at term boundaries or nightly. A term rollover then rotates every student's arc automatically off the calendar, with no manual step in the console.

6. Point outbound webhooks at your systems

   Settings → Integrations is also where outbound webhooks live. First Six POSTs help-request lifecycle events (help_request.created, help_request.crisis, help_request.assigned, help_request.resolved and the rest) to a URL you control, HMAC-signed so you can verify authenticity, with retry and backoff on failure.

   Use the Test button before you rely on it: it exercises the real delivery path against your endpoint. Verify the signature on your side from day one rather than trusting the source IP. Contract and signing details: webhooks.

7. Wire the crisis and help-desk channels deliberately

   These are separate from generic webhooks and they matter more. Crisis alerts fan out to an always-on staff email, and optionally to a Slack or Microsoft Teams incoming webhook and your help-desk queue. Configure them under Settings → Crisis (crisis alerting) and Settings → Integrations (help desk), and use the test action on each.

   Test these with a real recipient watching. A crisis path that silently fails is worse than one you never configured, because everyone assumes it works.

8. Add event feeds if you have them

   If campus events already live in a calendar system, subscribe First Six to the iCal feed rather than re-authoring events by hand. The feed syncs on a schedule and staff can force a sync from the console. Purely additive, so it is safe to add after launch: the event feed.

9. Decide on a vanity subdomain

   Optional, and cosmetic rather than functional, but it changes the URL students see. It needs a DNS record from your team plus configuration on the First Six side, so raise it early if you want it live for launch: custom subdomains.

Quick checklist

• OIDC app registered in your IdP, redirect URI matches exactly
• Client secret sent to First Six by a non-email channel
• Real staff account signs in end to end
• SIS secret generated and stored in your secret manager
• Roster pushed with dry_run and the validation report cleared
• Term calendar and enrolments pushed, if you run block teaching
• Outbound webhook endpoint receiving, and signature verified on your side
• Crisis and help-desk channels tested with a real recipient watching
• Event feed subscribed, if you have one
• Vanity subdomain raised, if you want one

Common questions

Related