LTI Registrations
API for accessing and configuring LTI registrations in a root account. LTI Registrations can be any of:
1.3 Dynamic Registration
1.3 manual installation (via JSON, URL, or UI)
1.1 manual installation (via XML, URL, or UI)
The Dynamic Registration process uses a different API endpoint to finalize the process and create the registration. The Registration guide has more details on that process.
A Lti::Registration object looks like:
// A registration of an LTI tool in Canvas
{
// the Canvas ID of the Lti::Registration object
"id": 2,
// Tool-provided registration name
"name": "My LTI Tool",
// Admin-configured friendly display name
"admin_nickname": "My LTI Tool (Campus A)",
// Tool-provided URL to the tool's icon
"icon_url": "https://mytool.com/icon.png",
// Tool-provided name of the tool vendor
"vendor": "My Tool LLC",
// The Canvas id of the account that owns this registration
"account_id": 1,
// Flag indicating if registration is internally-owned
"internal_service": false,
// Flag indicating if registration is locked for deployment
"lock_deploying": false,
// Flag indicating if registration is owned by this account, or inherited from
// Site Admin
"inherited": false,
// Flag indicating if registration is managed by this account's consortium
// parent and can't be modified here
"managed_by_parent": false,
// The Canvas ID of the template registration, if this registration is inherited
// from a template
"template_registration_id": 1,
// LTI version of the registration, either 1.1 or 1.3
"lti_version": "1.3",
// Flag indicating if registration was created using LTI Dynamic Registration.
// Only present if lti_version is 1.3
"dynamic_registration": false,
// The state of the registration. 'pending' means a tool created it via Dynamic
// Registration and an admin hasn't approved it yet.
"workflow_state": "active",
// Timestamp of the registration's creation
"created_at": "2024-01-01T00:00:00Z",
// Timestamp of the registration's last update
"updated_at": "2024-01-01T00:00:00Z",
// The user that created this registration. Not always present. If a string,
// this registration was created by Instructure.
"created_by": {"type":"UserDisplay"},
// The user that last updated this registration. Not always present. If a
// string, this registration was last updated by Instructure.
"updated_by": {"type":"UserDisplay"},
// The Canvas id of the root account
"root_account_id": 1,
// The binding for this registration and this account
"account_binding": {"type":"Lti::RegistrationAccountBinding"},
// The Canvas-style tool configuration for this registration
"configuration": {"type":"Lti::ToolConfiguration"}
}A Lti::RegistrationAccountBinding object looks like:
A Lti::LegacyConfiguration object looks like:
A Lti::ToolConfiguration object looks like:
A Lti::LaunchSettings object looks like:
A Lti::Placement object looks like:
A Lti::Overlay object looks like:
A Lti::OverlayVersion object looks like:
A Lti::PlacementOverlay object looks like:
A ListLtiRegistrationsResponse object looks like:
A ContextSearchResponse object looks like:
A SearchableAccount object looks like:
A SearchableCourse object looks like:
List LTI Registrations in an account
Lti::RegistrationsController#list
GET /api/v1/accounts/:account_id/lti_registrations
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations
GET /api/v1/accounts/:account_id/apps
Scope: url:GET|/api/v1/accounts/:account_id/apps
Returns all LTI registrations in the specified account. Includes registrations created in this account, those set to 'allow' from a parent root account (like Site Admin) and 'on' for this account, and those enabled 'on' at the parent root account level.
Request Parameters:
per_page
integer
The number of registrations to return per page. Defaults to 15.
page
integer
The page number to return. Defaults to 1.
sort
string
The field to sort by. Choices are: name, nickname, lti_version, installed, installed_by, updated_by, updated, and on. Defaults to installed.
dir
string
The order to sort the given column by. Defaults to desc. Allowed values: asc, desc
include[]
string
Array of additional data to include. Always includes [account_binding]. "account_binding":: the registration's binding to the given account "configuration":: the registration's Canvas-style tool configuration, without any overlays applied. "overlaid_configuration":: the registration's Canvas-style tool configuration, with all overlays applied. "overlay":: the registration's admin-defined configuration overlay
Example Request:
Returns a ListLtiRegistrationsResponse object.
Show an LTI Registration
Lti::RegistrationsController#show
GET /api/v1/accounts/:account_id/lti_registrations/:id
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/:id
GET /api/v1/accounts/:account_id/apps/:id
Scope: url:GET|/api/v1/accounts/:account_id/apps/:id
Return details about the specified LTI registration, including the configuration and account binding.
Request Parameters:
include[]
string
Array of additional data to include. Always includes [account_binding configuration]. "account_binding":: the registration's binding to the given account "configuration":: the registration's Canvas-style tool configuration, without any overlays applied. "overlaid_configuration":: the registration's Canvas-style tool configuration, with all overlays applied. "overlaid_legacy_configuration":: the registration's legacy-style configuration, with all overlays applied. "overlay":: the registration's admin-defined configuration overlay "overlay_versions":: the registration's overlay's edit history "api_developer_key_account_binding":: the account's binding to the registration's associated API developer key, if any
Example Request:
Returns a Lti::Registration object.
Create an LTI Registration
Lti::RegistrationsController#create
POST /api/v1/accounts/:account_id/lti_registrations
Scope: url:POST|/api/v1/accounts/:account_id/lti_registrations
POST /api/v1/accounts/:account_id/apps
Scope: url:POST|/api/v1/accounts/:account_id/apps
Create a new LTI Registration, as well as an associated Tool Configuration, Developer Key, and Registration Account binding. To install/create using Dynamic Registration, please use the Dynamic Registration API.
Request Parameters:
name
string
The name of the tool. If one isn't provided, it will be inferred from the configuration's title.
admin_nickname
string
A friendly nickname set by admins to override the tool name
vendor
string
The vendor of the tool
description
string
A description of the tool. Cannot exceed 2048 bytes.
configuration
string
[Required, Lti::ToolConfiguration
overlay
string
[Lti::Overlay] The overlay configuration for the tool. Overrides values in the base configuration.
unified_tool_id
string
The unique identifier for the tool, used for analytics. If not provided, one will be generated.
lock_deploying
boolean
When true, no new deployments of this registration can be created.
workflow_state
string
"on"/"off"/"allow" set the account binding state directly (binding vocabulary).
"active"/"inactive" set the registration state directly (registration vocabulary).
All five values update both the binding and the registration to equivalent states.
"allow" is only valid for Site Admin registrations. Defaults to "off". Allowed values: on, off, allow, active, inactive
Example Request:
Returns a Lti::Registration object.
Show an LTI Registration (via the client_id)
Lti::RegistrationsController#show_by_client_id
GET /api/v1/accounts/:account_id/lti_registration_by_client_id/:client_id
Scope: url:GET|/api/v1/accounts/:account_id/lti_registration_by_client_id/:client_id
GET /api/v1/accounts/:account_id/app_by_client_id/:client_id
Scope: url:GET|/api/v1/accounts/:account_id/app_by_client_id/:client_id
Returns details about the specified LTI registration, including the configuration and account binding.
Example Request:
Returns a Lti::Registration object.
Get LTI Registration by Unified Tool ID
Lti::RegistrationsController#show_by_utid
GET /api/v1/accounts/:account_id/lti_registrations/by_utid/:utid
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/by_utid/:utid
GET /api/v1/accounts/:account_id/apps/by_utid/:utid
Scope: url:GET|/api/v1/accounts/:account_id/apps/by_utid/:utid
Returns an LTI registration by looking up its unified_tool_id. Searches both manual configurations and IMS registrations. Only returns registrations that are active and accessible from the current account (owned by account, Site Admin, or has binding).
Example Request:
Returns a Lti::Registration object.
Check LTI Registration Install Status
Lti::RegistrationsController#install_status
GET /api/v1/accounts/:account_id/lti_registrations/install_status/:client_id
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/install_status/:client_id
GET /api/v1/accounts/:account_id/apps/install_status/:client_id
Scope: url:GET|/api/v1/accounts/:account_id/apps/install_status/:client_id
Returns the local installation status for a Site Admin LTI registration. If the developer key's registration is in Site Admin, returns the local copy in the current account (if installed). If the registration is already in the current account, returns it directly.
Example Request:
Returns a Lti::Registration object.
Update an LTI Registration
Lti::RegistrationsController#update
PUT /api/v1/accounts/:account_id/lti_registrations/:id
Scope: url:PUT|/api/v1/accounts/:account_id/lti_registrations/:id
PUT /api/v1/accounts/:account_id/apps/:id
Scope: url:PUT|/api/v1/accounts/:account_id/apps/:id
Update the specified LTI registration with the provided parameters. Note that updating the base tool configuration of a registration that is associated with a Dynamic Registration will return a 422. All other fields can be updated freely.
Request Parameters:
name
string
The name of the tool
admin_nickname
string
The admin-configured friendly display name for the registration
description
string
A description of the tool. Cannot exceed 2048 bytes.
configuration
string
[Lti::ToolConfiguration
overlay
string
[Lti::Overlay] The overlay configuration for the tool. Overrides values in the base configuration. Note that updating the overlay of a registration associated with a Dynamic Registration IS allowed.
workflow_state
string
"on"/"off"/"allow" set the account binding state directly (binding vocabulary) and will be deprecated soon.
"active"/"inactive" set the registration state directly (registration vocabulary).
All five values update both the binding and the registration to equivalent states.
"allow" is only valid for Site Admin registrations. Allowed values: on, off, allow, active, inactive
comment
string
A comment explaining why this change was made. Cannot exceed 2000 characters.
lock_deploying
boolean
When true, no new deployments of this registration can be created.
Example Request:
Returns a Lti::Registration object.
Reset an LTI Registration to Defaults
Lti::RegistrationsController#reset
PUT /api/v1/accounts/:account_id/lti_registrations/:id/reset
Scope: url:PUT|/api/v1/accounts/:account_id/lti_registrations/:id/reset
PUT /api/v1/accounts/:account_id/apps/:id/reset
Scope: url:PUT|/api/v1/accounts/:account_id/apps/:id/reset
Reset the specified LTI registration to its default settings in this context. This removes all customizations that were present in the overlay associated with this context.
Example Request:
Returns a Lti::Registration object.
Delete an LTI Registration
Lti::RegistrationsController#destroy
DELETE /api/v1/accounts/:account_id/lti_registrations/:id
Scope: url:DELETE|/api/v1/accounts/:account_id/lti_registrations/:id
DELETE /api/v1/accounts/:account_id/apps/:id
Scope: url:DELETE|/api/v1/accounts/:account_id/apps/:id
Remove the specified LTI registration
Example Request:
Returns a Lti::Registration object.
Bind an LTI Registration to a Root Account
Lti::RegistrationsController#bind
POST /api/v1/accounts/:account_id/lti_registrations/:id/bind
Scope: url:POST|/api/v1/accounts/:account_id/lti_registrations/:id/bind
POST /api/v1/accounts/:account_id/apps/:id/bind
Scope: url:POST|/api/v1/accounts/:account_id/apps/:id/bind
Enable or disable the specified LTI registration for the specified root account. To enable an inherited registration (eg from Site Admin), pass the registration's global ID.
Only allowed for root accounts.
<b>Specifics for centrally-managed/federated consortia:</b> Child root accounts may not bind inherited registrations. For parent root account, binding also applies to all child root accounts.
Request Parameters:
workflow_state
Required string
The desired state for this registration/account binding. Allowed values: on, off
Example Request:
Returns a Lti::RegistrationAccountBinding object.
Remove an Inherited LTI Registration
Lti::RegistrationsController#unbind
DELETE /api/v1/accounts/:account_id/lti_registrations/:id/bind
Scope: url:DELETE|/api/v1/accounts/:account_id/lti_registrations/:id/bind
DELETE /api/v1/accounts/:account_id/apps/:id/bind
Scope: url:DELETE|/api/v1/accounts/:account_id/apps/:id/bind
Deletes the account binding for this registration, effectively removing it from the account.
Only available when the lti_deactivate_registrations feature flag is enabled. Only valid for inherited (Site Admin) registrations — use destroy for registrations owned by this account.
Returns a Lti::RegistrationAccountBinding object.
Install an LTI Registration from a Template
Lti::RegistrationsController#install_from_template
POST /api/v1/accounts/:account_id/lti_registrations/:id/install_from_template
Scope: url:POST|/api/v1/accounts/:account_id/lti_registrations/:id/install_from_template
POST /api/v1/accounts/:account_id/apps/:id/install_from_template
Scope: url:POST|/api/v1/accounts/:account_id/apps/:id/install_from_template
This endpoint installs a local copy of a "template" LTI registration from Site Admin into the specified account. The local copy can then be customized for the account without affecting the template registration.
Only allowed for root accounts and for registrations from Site Admin marked as templates.
Example Request:
Returns a Lti::Registration object.
Search for Accounts and Courses
Lti::RegistrationsController#context_search
GET /api/v1/accounts/:account_id/lti_registrations/:registration_id/deployments/:deployment_id/context_search
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/:registration_id/deployments/:deployment_id/context_search
GET /api/v1/accounts/:account_id/apps/:registration_id/deployments/:deployment_id/context_search
Scope: url:GET|/api/v1/accounts/:account_id/apps/:registration_id/deployments/:deployment_id/context_search
This is a utility endpoint used by the Canvas Apps UI and may not serve general use cases.
Search for accounts and courses that match the search term on name, SIS id, or course code. Returns all matching accounts and courses, including those nested in sub-accounts. Returns bare-bones data about each account and course, and only up to 20 of each. Used to populate the search dropdowns when managing LTI registration availability.
Request Parameters:
only_children_of
string
Account ID. If provided, only searches within this account and only returns direct children of this account.
search_term
string
String to search for in account names, SIS ids, or course codes.
Example Request:
Returns a ContextSearchResponse object.
Get LTI Registration Overlay History
Lti::RegistrationsController#overlay_history
GET /api/v1/accounts/:account_id/lti_registrations/:id/overlay_history
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/:id/overlay_history
GET /api/v1/accounts/:account_id/apps/:id/overlay_history
Scope: url:GET|/api/v1/accounts/:account_id/apps/:id/overlay_history
Returns the overlay history items for the specified LTI registration.
Request Parameters:
limit
integer
The maximum number of history items to return. Defaults to 10. Maximum allowed is 100.
Example Request:
Returns a list of Lti::OverlayVersion objects.
Get LTI Registration History
Lti::RegistrationsController#history
GET /api/v1/accounts/:account_id/lti_registrations/:id/history
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/:id/history
GET /api/v1/accounts/:account_id/apps/:id/history
Scope: url:GET|/api/v1/accounts/:account_id/apps/:id/history
Returns the history entries for the specified LTI registration. This endpoint provides comprehensive change tracking for all fields associated with the registration, including registration fields, developer key changes, internal configuration changes, and overlay changes. Supports pagination using the page and per_page parameters. The default page size is 10.
Example Request:
Get LTI Registration Update Request
Lti::RegistrationsController#show_registration_update_request
GET /api/v1/accounts/:account_id/lti_registrations/:id/update_requests/:update_request_id
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/:id/update_requests/:update_request_id
GET /api/v1/accounts/:account_id/apps/:id/update_requests/:update_request_id
Scope: url:GET|/api/v1/accounts/:account_id/apps/:id/update_requests/:update_request_id
Retrieves details about a specific registration update request.
Request Parameters:
id
integer
The id of the registration.
update_request_id
integer
The id of the registration update request to retrieve.
include
string
no description Allowed values: String] Array of additional information to include [configuration, lti_registration
Example Request:
Get Latest LTI Registration Update Request
Lti::RegistrationsController#latest_registration_update_request
GET /api/v1/accounts/:account_id/lti_registrations/:id/latest_update_request
Scope: url:GET|/api/v1/accounts/:account_id/lti_registrations/:id/latest_update_request
GET /api/v1/accounts/:account_id/apps/:id/latest_update_request
Scope: url:GET|/api/v1/accounts/:account_id/apps/:id/latest_update_request
Retrieves the most recent update request for a registration, regardless of its status. Returns 404 if there are no update requests for this registration.
Request Parameters:
id
integer
The id of the registration.
Example Request:
Apply LTI Registration Update Requst
Lti::RegistrationsController#apply_registration_update_request
PUT /api/v1/accounts/:account_id/lti_registrations/:id/update_requests/:update_request_id/apply
Scope: url:PUT|/api/v1/accounts/:account_id/lti_registrations/:id/update_requests/:update_request_id/apply
PUT /api/v1/accounts/:account_id/apps/:id/update_requests/:update_request_id/apply
Scope: url:PUT|/api/v1/accounts/:account_id/apps/:id/update_requests/:update_request_id/apply
Applies a registration update request to an existing registration, replacing the existing configuration and overlay with the new values. If the request is rejected, marks it as rejected without applying changes.
Request Parameters:
id
integer
The id of the registration to update.
update_request_id
integer
The id of the registration update request to apply.
accepted
Required boolean
Whether to accept (true) or reject (false) the registration update request.
overlay
LtiConfigurationOverlay
Optional overlay data to apply on top of the new configuration.
comment
string
Optional comment explaining the reason for applying this update.
Example Request:
Returns a Lti::Registration object.
Last updated
Was this helpful?