LTI 1.3 API Reference

LTI 1.3 Advantage integration for Creatiq. Enables single-click content launch from any LMS, deep linking for content selection, Assignment and Grade Services (AGS) for gradebook sync, and Names and Role Provisioning Services (NRPS) for roster retrieval.

Base path: /lti

Endpoints

POST /lti/launch

Handle an LMS launch request (OIDC callback with id_token).

Description

Receives the id_token JWT from the LMS after the OIDC login flow. Validates the token against registered platforms, checks nonce freshness, then redirects the user to the appropriate Creatiq workspace URL.

Redirect logic:

1. If the token contains target_link_uri claim -- redirect there.
2. If the token contains resource_link.id -- redirect to /workspace?lti=true&resource={id}.
3. Otherwise -- redirect to /workspace?lti=true.

Request

Content-Type: application/x-www-form-urlencoded

Response

302 Redirect to workspace URL on success.

Errors

GET /lti/jwks

Public JWKS endpoint for LTI platforms to verify Creatiq's signatures.

Description

Returns the JSON Web Key Set containing Creatiq's RSA-256 public key. Platforms use this to verify deep-link response JWTs. Keys are auto-generated on first use (2048-bit RSA) and persisted in the lti_keys table.

Response

{
  "keys": [
    {
      "kty": "RSA",
      "n": "...",
      "e": "AQAB",
      "kid": "uuid",
      "use": "sig",
      "alg": "RS256"
    }
  ]
}

Errors

GET /lti/config

Get LTI platform configuration URLs.

Description

Returns the URLs that an LMS administrator needs when registering Creatiq as an LTI tool.

Response

{
  "success": true,
  "data": {
    "enabled": true,
    "launchUrl": "https://app.creatiq.com/lti/launch",
    "jwksUrl": "https://app.creatiq.com/lti/jwks",
    "deepLinkUrl": "https://app.creatiq.com/lti/deep-link",
    "loginUrl": "https://app.creatiq.com/lti/login"
  }
}

Errors

POST /lti/platforms

Register a new LTI platform.

Description

Registers an LMS platform for LTI 1.3 integration. Uses upsert logic -- if a platform with the same issuer + clientId already exists, it updates the record.

Request

{
  "issuer": "https://lms.example.com",
  "clientId": "creatiq-tool-12345",
  "name": "Example LMS",
  "authLoginUrl": "https://lms.example.com/auth/login",
  "authTokenUrl": "https://lms.example.com/auth/token",
  "keysetUrl": "https://lms.example.com/.well-known/jwks.json",
  "deploymentId": "deploy-001",
  "agsEndpoint": "https://lms.example.com/api/ags",
  "nrpsEndpoint": "https://lms.example.com/api/nrps"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "uuid",
    "issuer": "https://lms.example.com",
    "clientId": "creatiq-tool-12345",
    "name": "Example LMS",
    "authLoginUrl": "https://lms.example.com/auth/login",
    "authTokenUrl": "https://lms.example.com/auth/token",
    "keysetUrl": "https://lms.example.com/.well-known/jwks.json",
    "deploymentId": "deploy-001",
    "agsEndpoint": "https://lms.example.com/api/ags",
    "nrpsEndpoint": "https://lms.example.com/api/nrps",
    "createdAt": "2025-01-15T10:00:00.000Z",
    "updatedAt": "2025-01-15T10:00:00.000Z"
  }
}

Errors

POST /lti/deep-link

Create a deep linking response JWT for content selection.

Description

Generates a signed JWT that the LMS can use to register selected H5P content as LTI resource links. Each content item becomes an ltiResourceLink with a URL pointing to {appUrl}/h5p/play/{contentId}. The JWT is signed with RS256 using Creatiq's private key and expires in 5 minutes.

Request

{
  "platformId": "uuid-of-registered-platform",
  "contents": [
    {
      "type": "h5p",
      "title": "Interactive Quiz: Biology Chapter 3",
      "url": "https://app.creatiq.com/h5p/play/abc123",
      "contentId": "abc123"
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "jwt": "eyJhbGciOiJSUzI1NiIs..."
  }
}

The JWT payload contains:

• iss -- Creatiq app URL
• aud -- Platform issuer
• https://purl.imsglobal.org/spec/lti-dl/claim/content_items -- Array of ltiResourceLink items
• https://purl.imsglobal.org/spec/lti-dl/claim/msg -- "Content selected successfully"

Errors

Assignment and Grade Services (AGS)

GET /lti/ags/lineitems

List line items (gradebook columns) for a platform context.

Description

Retrieves all line items from the LMS gradebook for a given context (course). Internally acquires an OAuth 2.0 access token from the platform using the lineitem scope.

Query Parameters

Response

{
  "success": true,
  "data": [
    {
      "id": "https://lms.example.com/api/ags/lineitems/42",
      "label": "H5P Quiz Score",
      "scoreMaximum": 100,
      "resourceId": "abc123",
      "tag": "quiz",
      "startDateTime": "2025-01-01T00:00:00Z",
      "endDateTime": "2025-06-30T23:59:59Z"
    }
  ]
}

Errors

POST /lti/ags/lineitems

Create a line item in the LMS gradebook.

Request

{
  "platformId": "uuid",
  "contextId": "course-101",
  "label": "H5P Interactive Video Score",
  "scoreMaximum": 100,
  "resourceId": "content-abc123",
  "tag": "h5p-assessment"
}

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "https://lms.example.com/api/ags/lineitems/43",
    "label": "H5P Interactive Video Score",
    "scoreMaximum": 100,
    "resourceId": "content-abc123",
    "tag": "h5p-assessment"
  }
}

Errors

POST /lti/ags/scores

Publish a score to a specific line item.

Description

Publishes a learner's score to an LMS gradebook column. The score is submitted with activityProgress: "Completed" and gradingProgress: "FullyGraded". Internally acquires an OAuth 2.0 token with the score scope.

Request

{
  "platformId": "uuid",
  "lineItemUrl": "https://lms.example.com/api/ags/lineitems/42",
  "userId": "student-12345",
  "scoreGiven": 85,
  "scoreMaximum": 100,
  "comment": "Great work on the interactive quiz!"
}

Response

{
  "success": true,
  "message": "Score published"
}

Errors

Names and Role Provisioning Services (NRPS)

GET /lti/nrps/members

Fetch the membership list (roster) from an LMS platform.

Description

Retrieves all members of an LMS course context. Supports paginated responses -- follows Link header rel="next" up to 50 pages. LTI roles are mapped to simplified roles:

Query Parameters

Response

{
  "success": true,
  "data": {
    "id": "https://lms.example.com/api/nrps/memberships",
    "context": {
      "id": "course-101"
    },
    "members": [
      {
        "userId": "user-001",
        "roles": ["instructor"],
        "name": "Jane Doe",
        "email": "jane@example.com",
        "status": "Active"
      },
      {
        "userId": "user-002",
        "roles": ["learner"],
        "name": "John Smith",
        "email": "john@example.com",
        "status": "Active"
      }
    ]
  }
}

Errors

OAuth 2.0 Token Flow

All AGS and NRPS requests require an OAuth 2.0 access token from the LMS. The token service handles this transparently:

1. Check in-memory cache for a valid token (with 60-second buffer before expiry).
2. If no cached token, create a client_credentials grant request:
   • client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
   • client_assertion: JWT signed with RS256 (iss/sub = clientId, aud = authTokenUrl, exp = 5 min)
   • scope: Required LTI scopes for the operation
3. Cache the returned token for its expires_in duration.

LTI Scopes Used

Database Tables

lti_platforms

Unique constraint: (issuer, client_id).

lti_keys

lti_nonces

xAPI Integration

The AGS service listens for xAPI statements with score-trigger verbs (completed, passed, failed). When detected, these can trigger automatic grade passback to the LMS. This listener is initialized on service startup.