How a Launch Works

Every LTIAAS Connect launch follows the same four steps. Two of them are yours; two of them happen without any code on your side. Understanding the shape now makes the worked example much easier to follow.

The whole exchange happens in the learner's browser, usually inside an iframe you open when they click an activity.

Step 1 — You Start the Launch

A user clicks an activity in your LMS. Your front-end asks your back-end to start a launch, and your back-end calls LTIAAS:

POST https://your.ltiaas.com/api/launch/core/form
Authorization: Bearer <API_KEY>

{
  "clientId": "U0gIhEYg2rdIr4ABscEJ",
  "context": "0001",
  "resource": "14113",
  "user": "rKk4PdLgcRbqE4PdSW3iV0KhAmu2"
}

You are telling LTIAAS four things: which tool to launch, which course the launch belongs to, which activity within that course, and which user is launching. LTIAAS replies with a self-submitting HTML form. Render it in an iframe and the browser posts itself into the tool.

info

context, resource and user are your identifiers. LTIAAS treats them as opaque strings, carries them through the launch, and hands them back to you in step 3. Use whatever your database already uses.

caution

This call includes your API key, so it must happen on your back-end. Never call the LTIAAS API from a browser.

Step 2 — LTIAAS and the Tool Complete the Handshake

The tool receives the form post and begins the standard LTI® 1.3 OIDC handshake, calling back to LTIAAS's authentication endpoint. LTIAAS validates the request against the tool's registration — checking the redirect URI, the signed message hint, and the nonce — and confirms the tool is registered and active.

No code of yours runs during this step. Handling this handshake is the entire reason Connect exists.

Step 3 — LTIAAS Asks You Who the User Is

Once the handshake checks out, LTIAAS redirects the browser to the Launch URL you configured in the portal, with a signed token attached:

GET https://yourlms.com/lti-validate?payload=<JWT>

This is your second piece of code. Verify the JWT with your consumer public key, and you get back the context, resource and user values you sent in step 1, plus a metadata string that identifies this launch.

Now do the work only your LMS can do: confirm the user is logged in, confirm they may access this course, and gather their name, email and roles.

caution

The metadata value expires ten minutes after the launch begins. If this step waits on something slow — a login screen, a consent dialog — the launch will fail with INVALID_METADATA_PARAMETER. Authenticate the user before starting the launch, not during it.

Step 4 — You Answer, and the User Lands in the Tool

Send what you learned back to LTIAAS:

POST https://your.ltiaas.com/api/idtoken/core/form
Authorization: Bearer <API_KEY>

{
  "metadata": "<from the verified payload>",
  "user": { "id": "41", "name": "John Doe", "email": "john.doe@myschool.com", "roles": ["CONTEXT_LEARNER"] },
  "context": { "id": "0001", "label": "CS101", "title": "Computer Science 101", "type": ["CourseOffering"] },
  "resource": { "id": "14113", "title": "A cool learning tool" }
}

LTIAAS builds and signs an LTI® ID Token and returns another self-submitting form. Return it as the body of your Launch URL response, the browser posts it to the tool, and the user is in — logged in, in the right course, with the right role.

note

Notice the shape change: context and resource were plain strings in step 1, but they are objects here. Step 1 is routing information; step 4 is descriptive information. This catches almost everyone once.

After the Launch

If the tool uses LTI® services — reading a roster, creating a grade line, posting a score — it will now call LTIAAS with an access token. LTIAAS forwards each of those calls to your Service URL as a service request and translates your answer back into the protocol.

Those requests arrive whenever the tool decides to make them, which may be long after the learner has gone. They are not part of the launch.

Next Steps

• Configure your account — the URLs and keys this flow depends on.
• Register a tool — where clientId comes from.
• Your first launch — the same four steps as working code.