ilios · thecoolestguy · May 27, 2026
diff --git a/examples/1.3/canvas/Install.md b/examples/1.3/canvas/Install.md
@@ -0,0 +1,124 @@
+# Ilios LTI Integration with Canvas (Admin & Course Setup Guide)
+
+_Last updated: 2026-05-27_
+
+## Overview
+This guide walks Canvas administrators and course staff through adding and enabling the Ilios LTI (Learning Tools Interoperability) tool in Canvas using a Developer Key and installing it in a course.
+
+---
+
+## Prerequisites
+- Canvas **Admin** access (to create a Developer Key)
+- Course-level **Instructor/Designer** access (to install the app)
+- Ilios support contact (support@iliosproject.org)
+- Ilios LTI JSON configuration provided by Ilios (or your institution)
+
+---
+
+## Part 1 — Create and Enable the LTI Developer Key (Admin)
+
+1. Log in to Canvas as an administrator.
+2. Open the **Admin** menu.
+3. Select your root account.
+4. Navigate to **Developer Keys**.
+5. Click **+ Developer Key** → **+ LTI Key**.
+6. In **Method**, select **Paste JSON**.
+7. Paste the Ilios LTI JSON configuration.
+
+### Verify JSON Configuration
+Before saving, confirm:
+- Required fields like `client_id`, `title`, and `target_link_uri` are present
+- **Custom Fields** are included  
+  - ⚠️ Note: Custom fields pasted via JSON **do not display in the UI by default**, but they are still active.
+
+8. Enter:
+   - **Key Name / Title** (e.g., “Ilios LTI”)
+   - **Owner Email** (your or your admin email)
+9. Click **Save**.
+10. Ensure the Developer Key **State is set to ON (enabled)**.
+
+### Retrieve Client ID
+- Copy the **Client ID** from the “Details” column  
+  _or_  
+- Click **View in Canvas Apps** and copy it there
+
+---
+
+## Part 2 — Register Client ID with Ilios
+
+1. Email Ilios support:
+   - 📧 support@iliosproject.org
+2. Provide:
+   - Your **Client ID**
+3. Wait for confirmation that Ilios has updated their configuration.
+
+---
+
+## Part 3 — Install the Ilios App in a Course
+
+Before installing the LTI, visit Admin -> Apps -> Manage and make sure that the status shows "App is unlocked". If the status shows 'App is locked', then click the 'Unlock App' button to unlock it. An app cannot be installed into courses or navigation menus if it is locked.
+
+1. Navigate to your Canvas course (e.g., `ILIOSLTI13TEST`).
+2. Go to **Settings**.
+3. Select the **Apps** tab.
+4. Click **View App Configurations**.
+5. Click **+ App**.
+6. Choose **Configuration Type: By Client ID**.
+7. Paste the **Client ID**.
+8. Click **Submit**.
+9. Click **Install** when prompted.
+
+After the app has been installed, you can return to Admin -> Apps -> Manage and click the "Lock app" button to ensure it cannot be installed twice.
+
+---
+
+## Part 4 — Enable Ilios in Course Navigation
+
+1. Go to **Course Settings**.
+2. Select the **Navigation** tab.
+3. Locate **Ilios Dashboard** in the disabled items list.
+4. Click the **three-dot menu** (⋮).
+5. Select **Enable**.
+6. Drag to reorder if needed.
+7. Click **Save**.
+
+---
+
+## Verification
+
+- Confirm the **Ilios Dashboard** link appears in the course navigation
+- Click the link to verify:
+  - Successful launch
+  - No authentication errors
+  - Proper data loads from Ilios
+
+---
+
+## Troubleshooting
+
+### App does not appear in navigation
+- Ensure it is **enabled** in Navigation settings
+- Click **Save** after enabling
+
+### LTI launch fails
+- Confirm Ilios has registered your **Client ID**
+- Verify JSON configuration fields
+- Ensure Developer Key is **enabled**
+
+### Missing custom behavior
+- Double-check **custom fields** in the JSON
+- Remember: they may not appear in UI but still function
+
+---
+
+## Notes & Best Practices
+- Use a consistent naming convention for Developer Keys
+- Keep a record of Client IDs for each environment (test, staging, production)
+- Coordinate with Ilios before testing in production courses
+
+---
+
+## Support
+- Ilios Support: support@iliosproject.org
+- Canvas Admin Documentation: https://community.canvaslms.com/
+
diff --git a/examples/1.3/canvas/README.md b/examples/1.3/canvas/README.md
@@ -0,0 +1,226 @@
+# Ilios LTI 1.3 Canvas JSON Reference
+
+This document explains the fields in the Canvas Developer Key JSON and how each value is used in the LTI launch flow. For instructions on how to install the Ilios LTI 1.3 into Canvas, please see the the [installation documentation](Install.md).
+
+## Full JSON
+
+```json
+{
+  "title": "Ilios Dashboard",
+  "description": "Display Ilios Calendar Information",
+  "oidc_initiation_url": "https://lti.iliosproject.org/login",
+  "target_link_uri": "https://lti.iliosproject.org/dashboard",
+  "domain": "lti.iliosproject.org",
+  "tool_id": "ilios-dashboard-prod",
+  "public_jwk": {
+    "e": "AQAB",
+    "n": "vfgz4aS1N6cSWFlZMo5tGS2PVlwnTLbXKLTURGLbkPooi7-AJggkRzrJje2zacTpUX-lJdtoCH1gKMy2lgus1rH8N5XR64WWjig-9fXM6jj8SScZS4B_84wZ9FQMmbvylTwSJaMU2lGHxqn7dw73abVmTLY3laxatgscF_S1xY0XoavEloOpXC9XwTRbWEiaEcqc3NayO-fqdShB-Q2YOi4E1s8hCPdxvA3zoTEj5bybEKTRYzf-8diqOL4uHZcUD6h267o6k8orp87VEdINDGLoLs05MTb5ZxZ-hcp_qnUpg_P_gCclkzylLV3zymJcIXYtvZQGCQ23iG0mcowIGQ",
+    "alg": "RS256",
+    "kid": "a8ed9dc9-ae50-4544-99cf-fe0792d59bfc",
+    "kty": "RSA",
+    "use": "sig"
+  },
+  "extensions": [
+    {
+      "platform": "canvas.instructure.com",
+      "domain": "lti.iliosproject.org",
+      "tool_id": "ilios-dashboard-prod",
+      "privacy_level": "public",
+      "settings": {
+        "text": "Ilios Dashboard",
+        "placements": [
+          {
+            "placement": "course_navigation",
+            "text": "Ilios Dashboard",
+            "message_type": "LtiResourceLinkRequest",
+            "target_link_uri": "https://lti.iliosproject.org/dashboard",
+            "icon_url": "https://lti.iliosproject.org/icon.png",
+            "default": "enabled",
+            "visibility": "public",
+            "windowTarget": "_blank"
+          },
+          {
+            "placement": "account_navigation",
+            "text": "Ilios Dashboard Admin",
+            "message_type": "LtiResourceLinkRequest",
+            "target_link_uri": "https://lti.iliosproject.org/dashboard",
+            "icon_url": "https://lti.iliosproject.org/icon.png",
+            "default": "enabled",
+            "visibility": "admins",
+            "windowTarget": "_blank"
+          },
+          {
+            "placement": "user_navigation",
+            "text": "Ilios Dashboard",
+            "message_type": "LtiResourceLinkRequest",
+            "target_link_uri": "https://lti.iliosproject.org/dashboard",
+            "icon_url": "https://lti.iliosproject.org/icon.png",
+            "default": "enabled",
+            "visibility": "public",
+            "windowTarget": "_blank"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Top-level fields
+
+### `title`
+
+The human-readable name of the tool in Canvas. This is what admins and instructors are most likely to see in the Developer Key UI and in app installation flows.
+
+### `description`
+
+Short description of what the tool does. This is informational and helps explain the purpose of the tool in the admin interface.
+
+### `oidc_initiation_url`
+
+The login initiation endpoint for LTI 1.3. Canvas starts the OIDC login flow by sending the user here first. In this setup, it maps to the Lambda-backed `/login` route.
+
+### `target_link_uri`
+
+The launch destination Canvas uses after login. In this setup, it maps to the `/dashboard` route, which is where the tool receives the final LTI launch.
+
+### `domain`
+
+The hostname Canvas should associate with the tool. This should be the host only, without `https://` and without any path.
+
+### `tool_id`
+
+An internal identifier for the tool. This is useful for distinguishing environments such as dev, test, and prod.
+
+### `public_jwk`
+
+The tool’s public JSON Web Key. Canvas uses this to validate signatures related to the tool when needed. The important parts are:
+
+* `kty`: key type, here `RSA`
+* `n`: the RSA modulus
+* `e`: the exponent, usually `AQAB`
+* `alg`: signing algorithm, here `RS256`
+* `use`: intended purpose, here `sig`
+* `kid`: key ID used to identify the matching public key
+
+## Extension block
+
+### `extensions`
+
+Canvas uses the `extensions` array to describe the tool configuration for the platform.
+
+#### `platform`
+
+The platform identifier for Canvas. This tells Canvas which platform-specific settings apply.
+
+#### `domain`
+
+The tool’s hostname again, used inside the Canvas extension block.
+
+#### `tool_id`
+
+A stable internal identifier for this tool instance.
+
+#### `privacy_level`
+
+Controls how much user data the tool can receive. `public` is the broadest option and is commonly used when the tool needs standard launch claims.
+
+#### `settings`
+
+This block holds Canvas-specific placement settings.
+
+##### `text`
+
+The fallback label for the tool. If a placement does not override its own `text`, Canvas can use this label in the UI.
+
+##### `placements`
+
+An array of places where the tool should appear in Canvas.
+
+## Placement fields
+
+### `placement`
+
+Where the tool appears in Canvas.
+
+* `course_navigation` places the tool in the left-hand navigation for a course.
+* `account_navigation` places the tool in the account-level navigation. This is the best match for an admin context.
+* `user_navigation` places the tool in the global user menu.
+
+### `text`
+
+The label shown to users for that placement.
+
+### `message_type`
+
+The LTI message type used for the launch.
+
+* `LtiResourceLinkRequest` means a standard resource launch.
+
+### `target_link_uri`
+
+The URL Canvas should use when launching the tool from that placement. In this configuration, it points to `/dashboard`.
+
+### `icon_url`
+
+The optional icon Canvas can show for the placement. If the image URL is not available, this can be removed without affecting the launch.
+
+### `default`
+
+Whether the placement is enabled by default.
+
+* `enabled` means Canvas should expose it by default.
+* `disabled` means it is not shown by default.
+
+### `visibility`
+
+Controls who can see the placement.
+
+* `public` means anyone who can access the relevant Canvas context can see it.
+* `admins` means only account-level admin roles can see it.
+
+### `windowTarget`
+
+A best-effort hint that the tool should open in a new window or tab.
+
+* `_blank` attempts to open the launch in a new tab or window.
+* Canvas may not honor this uniformly in every placement.
+
+## Placement mapping
+
+### `course_navigation`
+
+This adds Ilios to the course sidebar so users can launch the tool from inside a course.
+
+### `account_navigation`
+
+This adds Ilios to the account-level navigation for admins. This is the placement to use when you want an admin-facing context.
+
+### `user_navigation`
+
+This adds Ilios to the user/global menu so it can be accessed outside a specific course context.
+
+## Practical notes
+
+* Keep `oidc_initiation_url` pointed at `/login`.
+* Keep `target_link_uri` pointed at `/dashboard`.
+* Keep `domain` as the host only.
+* Keep `tool_id` stable for each environment.
+* Remove `icon_url` if you do not have a real icon image to serve.
+* `windowTarget` is helpful, but the app should still be able to function if Canvas opens it in an iframe.
+
+## Suggested usage pattern
+
+For a dev environment:
+
+* `title` should clearly identify the environment.
+* `tool_id` should remain unique and stable.
+* `course_navigation` is the main placement for course users.
+* `account_navigation` is the best placement for admin-only access.
+* `user_navigation` is optional if you want a global shortcut.
+
+## Summary
+
+This JSON is a Canvas Developer Key configuration for an LTI 1.3 tool. The top-level fields describe the tool, the `public_jwk` publishes the tool’s public key, and the `extensions` block tells Canvas where to place the tool and how to launch it.
+
+