> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formswrite.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LTI integration

> Connect Formswrite to your LMS using LTI 1.3 for seamless single sign-on and tool launching

Formswrite supports **LTI 1.3** (Learning Tools Interoperability), the industry standard for integrating external tools with Learning Management Systems. This allows teachers and students to launch Formswrite directly from their LMS without a separate login.

<Info>
  LTI integration is available on **institutional plans**. Contact [dvir@formswrite.com](mailto:dvir@formswrite.com) to get started.
</Info>

## What is LTI?

LTI (Learning Tools Interoperability) is a standard developed by [IMS Global](https://www.imsglobal.org/) that allows LMS platforms to securely launch external tools. With LTI 1.3, authentication uses **OpenID Connect (OIDC)** and **JWT tokens** — no passwords are shared between systems.

### Benefits

* **Single sign-on** — teachers and students launch Formswrite from the LMS with one click
* **No separate accounts** — users are automatically provisioned via LTI
* **Secure** — uses industry-standard OIDC authentication with public/private key verification
* **Context-aware** — Formswrite knows which course and user is launching the tool

## Supported LMS platforms

Formswrite works with any LMS that supports LTI 1.3, including:

<CardGroup cols={3}>
  <Card title="Moodle" icon="graduation-cap">
    Version 3.7+ with LTI 1.3 support.
  </Card>

  <Card title="Canvas" icon="graduation-cap">
    Instructure Canvas with LTI 1.3 Developer Keys.
  </Card>

  <Card title="Blackboard" icon="graduation-cap">
    Blackboard Learn with LTI 1.3 tool registration.
  </Card>

  <Card title="Brightspace (D2L)" icon="graduation-cap">
    Desire2Learn Brightspace LTI Advantage.
  </Card>

  <Card title="Schoology" icon="graduation-cap">
    Schoology with LTI 1.3 app configuration.
  </Card>

  <Card title="Sakai" icon="graduation-cap">
    Sakai CLE with External Tools support.
  </Card>
</CardGroup>

## Setup overview

Setting up LTI involves two sides:

1. **Register Formswrite as a tool in your LMS** — provide Formswrite's URLs to your LMS
2. **Register your LMS as a platform in Formswrite** — provide your LMS's URLs to Formswrite

The process takes about 5 minutes. Detailed instructions for each LMS are below.

## Formswrite tool URLs

When configuring your LMS, you'll need to enter these Formswrite URLs:

| Setting                      | URL                                           |
| ---------------------------- | --------------------------------------------- |
| **Tool URL / Launch URL**    | `https://api.formswrite.com/api/lti/callback` |
| **Login Initiation URL**     | `https://api.formswrite.com/api/lti/login`    |
| **Public Keyset URL (JWKS)** | `https://api.formswrite.com/api/lti/jwks`     |
| **Redirection URI**          | `https://api.formswrite.com/api/lti/callback` |

<Tip>
  These URLs are also available in your Formswrite dashboard under **LTI Platforms** in the sidebar.
</Tip>

***

## Moodle setup

<Steps>
  <Step title="Add Formswrite as an external tool">
    1. In Moodle, go to **Site Administration → Plugins → Activity modules → External tool → Manage preconfigured tools**
    2. Click **Add preconfigured tool**
    3. Fill in the following:

    | Field              | Value                                         |
    | ------------------ | --------------------------------------------- |
    | Tool name          | `Formswrite`                                  |
    | Tool URL           | `https://api.formswrite.com/api/lti/callback` |
    | LTI version        | **LTI 1.3**                                   |
    | Public keyset      | `https://api.formswrite.com/api/lti/jwks`     |
    | Initiate login URL | `https://api.formswrite.com/api/lti/login`    |
    | Redirection URI(s) | `https://api.formswrite.com/api/lti/callback` |

    4. Under **Services**, set **IMS LTI Names and Role Provisioning** to *Use this service to retrieve members' information as per privacy settings*
    5. Under **Privacy**, set:
       * Share launcher's name: **Always**
       * Share launcher's email: **Always**
    6. Under **Miscellaneous**, set:
       * Default launch container: **New window**
       * Tool configuration usage: **Show in activity chooser and as a preconfigured tool**
    7. Click **Save changes**
  </Step>

  <Step title="Copy the platform details from Moodle">
    After saving, Moodle generates a **Client ID**. Click the edit icon on the Formswrite tool to find it.

    You'll need these values from your Moodle instance (replace `yourmoodle.com` with your domain):

    | Setting          | Value                                                   |
    | ---------------- | ------------------------------------------------------- |
    | Issuer           | `https://yourmoodle.com`                                |
    | Client ID        | *(generated by Moodle — shown on the tool config page)* |
    | Auth Login URL   | `https://yourmoodle.com/mod/lti/auth.php`               |
    | Access Token URL | `https://yourmoodle.com/mod/lti/token.php`              |
    | JWKS URL         | `https://yourmoodle.com/mod/lti/certs.php`              |

    <Info>
      For **Moodle Cloud** (moodlecloud.com), the URLs follow the same pattern: `https://yoursite.moodlecloud.com/mod/lti/auth.php`, etc.
    </Info>
  </Step>

  <Step title="Register the platform in Formswrite">
    1. Log in to Formswrite and go to **LTI Platforms** in the sidebar
    2. Click **Add Platform**
    3. Enter the platform details from step 2
    4. Click **Save**
  </Step>

  <Step title="Add Formswrite to a course">
    1. Go to any course in Moodle and turn on **Edit mode**
    2. Click the **+** button in a course section
    3. Select **Formswrite** from the activity chooser
    4. Click **Add** — the activity is created
    5. Students and teachers can now click the activity to launch Formswrite
  </Step>
</Steps>

***

## Canvas setup

<Steps>
  <Step title="Create a Developer Key">
    1. In Canvas, go to **Admin → Developer Keys**
    2. Click **+ Developer Key → + LTI Key**
    3. Set the method to **Manual Entry** and fill in:

    | Field                         | Value                                         |
    | ----------------------------- | --------------------------------------------- |
    | Key Name                      | `Formswrite`                                  |
    | Redirect URIs                 | `https://api.formswrite.com/api/lti/callback` |
    | Target Link URI               | `https://api.formswrite.com/api/lti/callback` |
    | OpenID Connect Initiation URL | `https://api.formswrite.com/api/lti/login`    |
    | JWK Method                    | **Public JWK URL**                            |
    | Public JWK URL                | `https://api.formswrite.com/api/lti/jwks`     |

    4. Click **Save** and note the **Client ID** (a long number shown in the Details column)
    5. Set the key state to **ON**
  </Step>

  <Step title="Add the external tool to a course">
    1. Go to **Course Settings → Apps → + App**
    2. Configuration type: **By Client ID**
    3. Enter the Client ID from step 1
    4. Click **Submit** and **Install**
  </Step>

  <Step title="Register the platform in Formswrite">
    1. In Formswrite, go to **LTI Platforms → Add Platform**
    2. Enter these values:

    | Setting          | Value                                                       |
    | ---------------- | ----------------------------------------------------------- |
    | Issuer           | `https://canvas.instructure.com` (or your Canvas domain)    |
    | Client ID        | *(from step 1)*                                             |
    | Auth Login URL   | `https://canvas.instructure.com/api/lti/authorize_redirect` |
    | Access Token URL | `https://canvas.instructure.com/login/oauth2/token`         |
    | JWKS URL         | `https://canvas.instructure.com/api/lti/security/jwks`      |

    <Info>
      For **self-hosted Canvas**, replace `canvas.instructure.com` with your Canvas domain.
    </Info>

    3. Click **Save**
  </Step>
</Steps>

***

## Blackboard setup

<Steps>
  <Step title="Register Formswrite as an LTI tool">
    1. In Blackboard, go to **System Admin → Integrations → LTI Tool Providers**
    2. Click **Register LTI 1.3/Advantage Tool**
    3. Enter the **Client ID** (you'll get this after registering the tool)

    Or use the manual registration:

    | Field                       | Value                                         |
    | --------------------------- | --------------------------------------------- |
    | Tool Provider URL           | `https://api.formswrite.com/api/lti/callback` |
    | Tool Provider OIDC Auth URL | `https://api.formswrite.com/api/lti/login`    |
    | Tool Provider JWKS URL      | `https://api.formswrite.com/api/lti/jwks`     |

    4. Click **Submit**
    5. Copy the **Application ID**, **Deployment ID**, and other platform details
  </Step>

  <Step title="Register the platform in Formswrite">
    1. In Formswrite, go to **LTI Platforms → Add Platform**
    2. Enter the Blackboard platform details (issuer, client ID, auth URLs)
    3. Include the **Deployment ID** if provided
    4. Click **Save**
  </Step>
</Steps>

***

## General LTI 1.3 setup

For any LMS not listed above, the process follows the same pattern:

1. In your LMS, register a new **LTI 1.3 external tool** using the [Formswrite tool URLs](#formswrite-tool-urls) listed above
2. Your LMS will generate a **Client ID** and provide its own platform URLs (issuer, auth endpoint, token endpoint, JWKS URL)
3. In Formswrite, go to **LTI Platforms → Add Platform** and enter those platform URLs
4. Add the tool to a course and test the launch

## How the launch flow works

When a user clicks the Formswrite activity in their LMS:

```
LMS                          Formswrite Backend                    Formswrite App
 |                                  |                                    |
 |-- POST /api/lti/login ---------->|                                    |
 |   (iss, login_hint, client_id)   |                                    |
 |                                  |-- verify platform registration     |
 |                                  |-- generate state + nonce           |
 |<-- redirect to LMS auth --------|                                    |
 |                                  |                                    |
 |-- POST /api/lti/callback ------->|                                    |
 |   (signed JWT id_token)          |                                    |
 |                                  |-- verify JWT via JWKS              |
 |                                  |-- verify state + nonce             |
 |                                  |-- find or create user account      |
 |                                  |-- set session cookie               |
 |                                  |-- redirect ----------------------->|
 |                                  |                                    |
 |                                  |                          Formswrite Dashboard
```

## Managing platforms

Site administrators can manage LTI platform registrations from the **LTI Platforms** page in the Formswrite dashboard sidebar.

| Action                    | Description                                        |
| ------------------------- | -------------------------------------------------- |
| **Add Platform**          | Register a new LMS connection                      |
| **Edit**                  | Update platform URLs or credentials                |
| **Activate / Deactivate** | Temporarily disable a platform without deleting it |
| **Delete**                | Permanently remove a platform registration         |

<Warning>
  The LTI Platforms page is only visible to Formswrite site administrators. If you don't see it in the sidebar, contact your Formswrite admin.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Launch fails with 'Platform not found'">
    The **Issuer** URL in Formswrite must exactly match what the LMS sends. Check for:

    * Trailing slashes (`https://moodle.com` vs `https://moodle.com/`)
    * Protocol (`https://` vs `http://`)
    * Subdomain (`www.moodle.com` vs `moodle.com`)
  </Accordion>

  <Accordion title="Launch opens a blank page or times out">
    This is usually a **cookie issue**. LTI launches happen in iframes or popups, and some browsers block third-party cookies. Solutions:

    * Set the LMS tool to open in a **new window** (not embedded)
    * Ensure your browser allows third-party cookies for `formswrite.com`
  </Accordion>

  <Accordion title="User lands on sign-in page instead of dashboard">
    The session cookie may not have been set. Check that:

    * The **Redirection URI** in your LMS matches `https://api.formswrite.com/api/lti/callback`
    * Your LMS is sending the user's **email** in the LTI payload (check privacy settings)
  </Accordion>

  <Accordion title="'Access Denied' when opening LTI Platforms page">
    The LTI Platforms admin page is restricted to Formswrite site administrators. Contact your admin to have your email added to the authorized list.
  </Accordion>

  <Accordion title="Client ID mismatch error">
    Ensure the **Client ID** registered in Formswrite exactly matches the one generated by your LMS. Copy-paste it to avoid typos.
  </Accordion>
</AccordionGroup>

## Security

Formswrite's LTI implementation follows best practices:

* **JWT verification** — all launch tokens are verified against the platform's public JWKS endpoint
* **State and nonce** — stored in Redis with a 10-minute TTL to prevent replay attacks
* **HTTPS only** — all LTI endpoints require HTTPS
* **No shared secrets** — LTI 1.3 uses public/private key pairs, not shared secrets (unlike LTI 1.1)