How launches work
A launch is what happens when someone opens your app from inside an LMS course. Voshi sits between the LMS and your app: it handles the LMS integration and hands the user to your app with everything you need in a single signed token.
The lifecycle
- Someone launches your app. An instructor or student clicks your app's placement in a course. The LMS hands the launch to Voshi — your app isn't involved yet.
- Voshi forwards the launch to you. Voshi sends the user's browser to your app's callback URL with a
POSTof a single field,launch_data: a signed JWT identifying the school, course, user, and which of your locations was launched. - Your app takes over. You verify the JWT, create your own session, and render whatever the user should see. From here on, the user is simply navigating your app.
Nothing precedes step 1 for people: Voshi doesn't announce a school, course, or student before they launch, so the launch is also where your app first hears about them. See what a launch tells you about.
Courses are the exception. The first time anyone — student, instructor, or admin — launches into a course, Voshi tells your app to set that course up, and holds the launch until your app says it's ready. See How provisioning works. So any launch that does land on your callback URL names a course your app has already prepared.
The launch POST arrives through the user's browser, not from a Voshi server. That has two consequences: the JWT's signature is the only thing standing between you and a forged launch (so verify it, always), and Voshi never sees your app's response — errors on your side are between your app and the user.
What arrives in the launch
The JWT identifies the user (a stable ID, their course membership, and their role groups), the course, the school, your launched location, whether grade passback is available, and URLs for your four app data storage rows. See the Launch Data reference for every field.
Three properties worth knowing up front:
- All IDs are Voshi's own IDs — stable across launches, but never the LMS's internal IDs.
- No PII on student launches. Name and email arrive only when the launching user is course staff (
manager,instructor, orassistant); on every other launch they arenull. Recognize a returning user byuser.id. - One token, one session. Tokens expire after 2 hours, but you shouldn't rely on that — trade the token for your own session on first use and don't accept the same token twice.
How placements happen (deep linking)
Instructors place your app into their course through a content picker that Voshi presents. Your app's only part in it is one server-to-server request: Voshi asks your Locations URL what you currently offer, and shows the instructor that list. They pick a destination, optionally rename the placement, and Voshi handles the rest (for assessment locations, a gradebook column is created as part of the placement).
Because the list is fetched at placement time, what instructors can place is always current. What arrives in a launch, though, is the copy Voshi captured when that placement was made — so drive your app off location.extid and your own data rather than treating the launch claim as live configuration. See Concepts, Locations, and Serving your locations.