Skip to content

Deep Linking

The /api/deeplinking endpoints implement the Deep Linking Service are used to create Tool Links in the Platform.

Deep Linking Flow

The Deep Linking flow starts in the same way as a regular launch, but the user is redirected to a resource selection endpoint instead:

  • The LTIaaS server will receive the deep linking launch on behalf of the Tool;
  • Validate the IdToken and store it in the database;
  • Redirect the user to the Tool's Deep Linking URL, configured during the LTIaaS onboarding process, passing the ltik representing the current launch context.
  • Tool displays the resource selection screen.
  • Tool makes a request to the deep linking endpoint with the selected resources.
  • LTIaaS responds with the generated self-submitting form.
  • Tool appends form to HTML body.
  • Form self submits and finalizes deep linking process.

Create Deep Linking form

ROUTE METHOD AUTHENTICATION METHOD
/api/deeplinking/form POST LTIK_AUTH_V1

Request

Parameters

PARAMETER TYPE LOCATION REQUIRED
contentItems Array body ✔️
options Object body
  • contentItems: An array of resources formatted as Content Items following the IMS Content Item specification. The most commonly used type of contentItem is ltiResourceLink, the Tool Link.
  • options: An object containing one or more of the following fields:
    • If the deep linking process succeeded:
      • options.message - Message displayed to the user if the deep linking process is successfully completed.
      • options.log - Log generated by the Platform if the deep linking process is successfully completed.
    • If the deep linking process failed:
      • options.errMessage - Message displayed to the user if the deep linking process finishes with an error.
      • options.errLog - Log generated by the Platform if the deep linking process finishes with an error.

Sending options.errMessage or options.errLog will cause the LMS to reject the deep linking submission and display the error message.

Example usage

// Calling the API in the backend
app.post('/submit-link', async (req, res, next) => {
  const ltik = req.query.ltik
  const link = {
    contentItems: [{
      type: 'ltiResourceLink',
      url: 'https://your.ltiaas.com?resourceid=123456',
      title: 'Resource'
    }],
    options: { 
      message: 'Deep Linking successful!',
      log: 'deep_linking_successful'
    }
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.post('https://your.ltiaas.com/api/deeplinking/form', { json: link, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

// Append self-submitting form to HTML body in the frontend
$('body').append(response.form)

Specifying resources when using deep linking

The url field of a content item should point to your LTIaaS instance. In order to pass parameters to your Tool and identify the selected resource you can add query parameters to the URL.

Example:

  • URL passed inside the Deep Linking content item: https://your.ltiaas.com?resource=1234
  • URL the user will be redirected to after a successful launch from the created resource: https://tool.com?resource=1234

Response

Returns a self-submitting form with the signed JWT containing the selected resources that must be appended to the HTML body.

  • form - Self-submitting form that must be appended to the HTML body.

Example response

{ 
  form: '<form id="ltijs_submit" style="display: none;" action="https://ltiadvantagevalidator.imsglobal.org/ltitool/deeplinkresponse.html" method="POST"><input type="hidden" name="JWT" value="eyJhbGciOiJIUzIVCJ9.eyJzdWIbmFtZSI6IG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKV_adQssw5c" /></form><script>document.getElementById("ltijs_submit").submit()</script>' 
}

Create Deep Linking Message

If you want to build your own self-submitting form, it is also possible to create only the signed JWT message.

ROUTE METHOD AUTHENTICATION METHOD
/api/deeplinking/message POST LTIK_AUTH_V1

Request

Parameters

PARAMETER TYPE LOCATION REQUIRED
contentItems Array body ✔️
options Object body
  • contentItems: An array of resources formatted as Content Items following the IMS Content Item specification. The most commonly used type of contentItem is ltiResourceLink, the Tool Link.
  • options: An object containing one or more of the following fields:
    • If the deep linking process succeeded:
      • options.message - Message displayed to the user if the deep linking process is successfully completed.
      • options.log - Log generated by the Platform if the deep linking process is successfully completed.
    • If the deep linking process failed:
      • options.errMessage - Message displayed to the user if the deep linking process finishes with an error.
      • options.errLog - Log generated by the Platform if the deep linking process finishes with an error.

Sending options.errMessage or options.errLog will cause the LMS to reject the deep linking submission and display the error message.

Example usage

// Calling the API in the backend
app.post('/submit-link', async (req, res, next) => {
  const ltik = req.query.ltik
  const link = {
    contentItems: [{
      type: 'ltiResourceLink',
      url: 'https://your.ltiaas.com?resourceid=123456',
      title: 'Resource'
    }],
    options: { 
      message: 'Deep Linking successful!',
      log: 'deep_linking_successful'
    }
  }
  const authorizationHeader = `LTIK-AUTH-V1 Token=${ltik}, Additional=Bearer ${API_KEY}`
  const response = await request.post('https://your.ltiaas.com/api/deeplinking/message', { json: link, headers: { Authorization: authorizationHeader } }).json()
  return res.send(response)
})

// Building self-submitting formn and appending it to HTML body in the frontend
const form = '<form id="ltijs_submit" style="display: none;" action="' + response.endpoint + '" method="POST"><input type="hidden" name="JWT" value="' + response.message + '" /></form><script>document.getElementById("ltijs_submit").submit()</script>'
return form
$('body').append(form)

Specifying resources when using deep linking

The url field of a content item should point to your LTIaaS instance. In order to pass parameters to your Tool and identify the selected resource you can add query parameters to the URL.

Example:

  • URL passed inside the Deep Linking content item: https://your.ltiaas.com?resource=1234
  • URL the user will be redirected to after a successful launch from the created resource: https://tool.com?resource=1234

Response

Returns a signed JWT containing the selected resources that must be inserted in a self-submitting form and appended to the HTML body, and the endpoint to which the message has to be submitted to in order to finish the Deep Linking flow.

  • message - Signed JWT containing the selected resources that must be inserted in a self-submitting form and appended to the HTML body.
  • endpoint - Endpoint to which the message has to be submitted to in order to finish the Deep Linking flow

Example response

{ 
  message: 'eyJhbGciOiJIUzIVCJ9.eyJzdWIbmFtZSI6IG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKV_adQssw5c',
  endpoint: 'https://ltiadvantagevalidator.imsglobal.org/ltitool/deeplinkresponse.html'
}