ltijs Documentation

For requests not directed at reserved endpoints, Ltijs validates them by matching a session cookie with an ltik JWT token. The ltik token must be provided in one of the following ways (in this order of priority):

1. LTIK-AUTH-V1 Authorization header: Authorization: LTIK-AUTH-V1 Token=<ltik>, Additional=<additional>
2. Query parameter: https://tool.com?ltik=<ltik>
3. Request body: { "ltik": "<ltik>" }
4. Bearer Authorization header: Authorization: Bearer <ltik>

When using LTIK-AUTH-V1, req.headers.authorization will only contain the Additional portion, while the ltik is available in req.token.

// Example LTIK-AUTH-V1 header
// Authorization: LTIK-AUTH-V1 Token=eyJhbGci... , Additional=Bearer KxwRJS...

By default, ltijs uses MongoDB to store and manage server data. You must have MongoDB installed and running.

If you prefer other databases, you can use community-maintained database plugins that follow the same structure as the main database class:

• Firestore Plugin: @examind-ai/ltijs-firestore
• Sequelize Plugin: Supports MySQL and PostgreSQL via @Cvmcosta/ltijs-sequelize.

By setting ltiaas: true in the options parameter, Ltijs removes the session cookie request authentication step. In this mode, all request validation is performed via the ltik token. Unlike devMode, ltiaas mode still creates and validates login state cookies.

lti.setup('EXAMPLEKEY', 
  { url: 'mongodb://localhost/database' }, 
  {
    ltiaas: true
  }
)

The contentItems parameter accepts a single content item object or an array of objects following the LTI® 1.3 content item specification.

Important: Ltijs does not guarantee all items will be sent. It only sends items that fit within the platform's accepted item types and allowed quantity. For example, if a platform only allows one content item per request, only the first item in your array will be sent.

const items = [
  {
    type: 'ltiResourceLink',
    title: 'LTI resource',
    url: 'https://your.ltijs.com?resource=resource1',
    custom: {
      resource: 'resource1'
    }
  },
  {
    type: 'link',
    title: 'Link',
    url: 'https://link.com'
  }
]

const message = await lti.DeepLinking.createDeepLinkingMessage(token, items, { message: 'Successfully registered resources!' })

Ltijs supports multiple platforms sharing the same platform URL (common in Canvas implementations) by using unique clientIds.

• To get all platforms for a URL: Call lti.getPlatform(platformUrl). This returns an Array of Platform objects.
• To get a specific platform: Call lti.getPlatform(platformUrl, clientId). This returns a single Platform object.

You can use the clientId field from the IdToken object to retrieve the correct platform during an onConnect event.

// Returns [Platform, Platform]
const plats = await lti.getPlatform('http://plat.com')

// Returns Platform
const plat = await lti.getPlatform('http://plat.com', 'CLIENTID2')

// Usage in onConnect
lti.onConnect((token, request, response, next) => {
    const plat = await lti.getPlatform(token.iss, token.clientId)
})

The lti object (accessed via require('ltijs').Provider) is a singleton. You should call lti.setup() exactly once in your application entry point. Once setup, the same lti instance can be imported into other files to access services like lti.Grade, lti.Platform, or the underlying Express app.

// a.js (Entry point)
const lti = require('ltijs').Provider

lti.setup('LTIKEY', { url: 'mongodb://localhost/database' }, { appRoute: '/', loginRoute: '/login' })

lti.deploy()

// b.js (Other file)
const lti = require('ltijs').Provider
// Access services like Grade
await lti.Grade.scorePublish(token, grade)

Ltijs provides implementations for several LTI Advantage services. Note that detailed class documentation for these services is hosted externally at the official documentation site.

Supported services include:

• Deep Linking Service: For facilitating the selection of content during tool launch.
• Assignment and Grades Service: For managing assignments and grade transfers.
• Names and Roles Provisioning Service: For managing user identities and roles within a context.
• Dynamic Registration Service: For allowing tools to register themselves with a platform automatically.

To use ltijs in your project, install it using the npm package manager.

$ npm install ltijs