External Tools API

API for accessing and configuring external tools on accounts and courses. "External tools" are IMS LTI links: http://www.imsglobal.org/developers/LTI/index.cfm

NOTE: Placements not documented here should be considered beta features and are not officially supported.

List external tools ExternalToolsController#index

GET /api/v1/courses/:course_id/external_tools

Scope: url:GET|/api/v1/courses/:course_id/external_tools

GET /api/v1/accounts/:account_id/external_tools

Scope: url:GET|/api/v1/accounts/:account_id/external_tools

GET /api/v1/groups/:group_id/external_tools

Scope: url:GET|/api/v1/groups/:group_id/external_tools

Returns the paginated list of external tools for the current context. See the get request docs for a single tool for a list of properties on an external tool.

Request Parameters:

Parameter Type Description
search_term string

The partial name of the tools to match and return.
selectable boolean

If true, then only tools that are meant to be selectable are returned
include_parents boolean

If true, then include tools installed in all accounts above the current context

Example Response:

[
 {
   "id": 1,
   "domain": "domain.example.com",
   "url": "http://www.example.com/ims/lti",
   "consumer_key": "key",
   "name": "LTI Tool",
   "description": "This is for cool things",
   "created_at": "2037-07-21T13:29:31Z",
   "updated_at": "2037-07-28T19:38:31Z",
   "privacy_level": "anonymous",
   "custom_fields": {"key": "value"},
   "account_navigation": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "text": "...",
        "url": "...",
        "label": "...",
        "selection_width": 50,
        "selection_height":50
   },
   "assignment_selection": null,
   "course_home_sub_navigation": null,
   "course_navigation": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "text": "...",
        "url": "...",
        "default": "disabled",
        "enabled": "true",
        "visibility": "public",
        "windowTarget": "_blank"
   },
   "editor_button": {
        "canvas_icon_class": "icon-lti",
        "icon_url": "...",
        "message_type": "ContentItemSelectionRequest",
        "text": "...",
        "url": "...",
        "label": "...",
        "selection_width": 50,
        "selection_height": 50
   },
   "homework_submission": null,
   "link_selection": null,
   "migration_selection": null,
   "resource_selection": null,
   "tool_configuration": null,
   "user_navigation": null,
   "selection_width": 500,
   "selection_height": 500,
   "icon_url": "...",
   "not_selectable": false
 },
 { ...  }
]

Get a sessionless launch url for an external tool. ExternalToolsController#generate_sessionless_launch

GET /api/v1/courses/:course_id/external_tools/sessionless_launch

Scope: url:GET|/api/v1/courses/:course_id/external_tools/sessionless_launch

GET /api/v1/accounts/:account_id/external_tools/sessionless_launch

Scope: url:GET|/api/v1/accounts/:account_id/external_tools/sessionless_launch

Returns a sessionless launch url for an external tool.

NOTE: Either the id or url must be provided unless launch_type is assessment or module_item.

Request Parameters:

Parameter Type Description
id string

The external id of the tool to launch.
url string

The LTI launch url for the external tool.
assignment_id string

The assignment id for an assignment launch. Required if launch_type is set to “assessment”.
module_item_id string

The assignment id for a module item launch. Required if launch_type is set to “module_item”.
launch_type string

The type of launch to perform on the external tool. Placement names (eg. “course_navigation”) can also be specified to use the custom launch url for that placement; if done, the tool id must be provided.

Allowed values: assessment, module_item

API response field:

  • id

    The id for the external tool to be launched.

  • name

    The name of the external tool to be launched.

  • url

    The url to load to launch the external tool for the user.

Example Request:

Finds the tool by id and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'id=<external_tool_id>'

Finds the tool by launch url and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'url=<lti launch url>'

Finds the tool associated with a specific assignment and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'launch_type=assessment' \
     -F 'assignment_id=<assignment_id>'

Finds the tool associated with a specific module item and returns a sessionless launch url
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'launch_type=module_item' \
     -F 'module_item_id=<module_item_id>'

Finds the tool by id and returns a sessionless launch url for a specific placement
curl 'https://<canvas>/api/v1/courses/<course_id>/external_tools/sessionless_launch' \
     -H "Authorization: Bearer <token>" \
     -F 'id=<external_tool_id>' \
     -F 'launch_type=<placement_name>'

Get a single external tool ExternalToolsController#show

GET /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:GET|/api/v1/courses/:course_id/external_tools/:external_tool_id

GET /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:GET|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Returns the specified external tool.

API response field:

  • id

    The unique identifier for the tool

  • domain

    The domain to match links against

  • url

    The url to match links against

  • consumer_key

    The consumer key used by the tool (The associated shared secret is not returned)

  • name

    The name of the tool

  • description

    A description of the tool

  • created_at

    Timestamp of creation

  • updated_at

    Timestamp of last update

  • privacy_level

    What information to send to the external tool, “anonymous”, “name_only”, “public”

  • custom_fields

    Custom fields that will be sent to the tool consumer

  • account_navigation

    The configuration for account navigation links (see create API for values)

  • assignment_selection

    The configuration for assignment selection links (see create API for values)

  • course_home_sub_navigation

    The configuration for course home navigation links (see create API for values)

  • course_navigation

    The configuration for course navigation links (see create API for values)

  • editor_button

    The configuration for a WYSIWYG editor button (see create API for values)

  • homework_submission

    The configuration for homework submission selection (see create API for values)

  • link_selection

    The configuration for link selection (see create API for values)

  • migration_selection

    The configuration for migration selection (see create API for values)

  • resource_selection

    The configuration for a resource selector in modules (see create API for values)

  • tool_configuration

    The configuration for a tool configuration link (see create API for values)

  • user_navigation

    The configuration for user navigation links (see create API for values)

  • selection_width

    The pixel width of the iFrame that the tool will be rendered in

  • selection_height

    The pixel height of the iFrame that the tool will be rendered in

  • icon_url

    The url for the tool icon

  • not_selectable

    whether the tool is not selectable from assignment and modules

Example Response:

{
  "id": 1,
  "domain": "domain.example.com",
  "url": "http://www.example.com/ims/lti",
  "consumer_key": "key",
  "name": "LTI Tool",
  "description": "This is for cool things",
  "created_at": "2037-07-21T13:29:31Z",
  "updated_at": "2037-07-28T19:38:31Z",
  "privacy_level": "anonymous",
  "custom_fields": {"key": "value"},
  "account_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "label": "...",
       "selection_width": 50,
       "selection_height":50
  },
  "assignment_selection": null,
  "course_home_sub_navigation": null,
  "course_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "default": "disabled",
       "enabled": "true",
       "visibility": "public",
       "windowTarget": "_blank"
  },
  "editor_button": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "message_type": "ContentItemSelectionRequest",
       "text": "...",
       "url": "...",
       "label": "...",
       "selection_width": 50,
       "selection_height": 50
  },
  "homework_submission": null,
  "link_selection": null,
  "migration_selection": null,
  "resource_selection": null,
  "tool_configuration": null,
  "user_navigation": {
       "canvas_icon_class": "icon-lti",
       "icon_url": "...",
       "text": "...",
       "url": "...",
       "default": "disabled",
       "enabled": "true",
       "visibility": "public",
       "windowTarget": "_blank"
  },
  "selection_width": 500,
  "selection_height": 500,
  "icon_url": "...",
  "not_selectable": false
}

Create an external tool ExternalToolsController#create

POST /api/v1/courses/:course_id/external_tools

Scope: url:POST|/api/v1/courses/:course_id/external_tools

POST /api/v1/accounts/:account_id/external_tools

Scope: url:POST|/api/v1/accounts/:account_id/external_tools

Create an external tool in the specified course/account. The created tool will be returned, see the “show” endpoint for an example.

Request Parameters:

Parameter Type Description
name Required string

The name of the tool
privacy_level Required string

What information to send to the external tool.

Allowed values: anonymous, name_only, public

consumer_key Required string

The consumer key for the external tool
shared_secret Required string

The shared secret with the external tool
description string

A description of the tool
url string

The url to match links against. Either “url” or “domain” should be set, not both.
domain string

The domain to match links against. Either “url” or “domain” should be set, not both.
icon_url string

The url of the icon to show for this tool
text string

The default text to show for this tool
custom_fields[field_name] string

Custom fields that will be sent to the tool consumer; can be used multiple times
account_navigation[url] string

The url of the external tool for account navigation
account_navigation[enabled] boolean

Set this to enable this feature
account_navigation[text] string

The text that will show on the left-tab in the account navigation
account_navigation[selection_width] string

The width of the dialog the tool is launched in
account_navigation[selection_height] string

The height of the dialog the tool is launched in
account_navigation[display_type] string

The layout type to use when launching the tool. Must be “full_width”, “borderless”, or “default”
user_navigation[url] string

The url of the external tool for user navigation
user_navigation[enabled] boolean

Set this to enable this feature
user_navigation[text] string

The text that will show on the left-tab in the user navigation
user_navigation[visibility] string

Who will see the navigation tab. “admins” for admins, “public” or “members” for everyone

Allowed values: admins, members, public

course_home_sub_navigation[url] string

The url of the external tool for right-side course home navigation menu
course_home_sub_navigation[enabled] boolean

Set this to enable this feature
course_home_sub_navigation[text] string

The text that will show on the right-side course home navigation menu
course_home_sub_navigation[icon_url] string

The url of the icon to show in the right-side course home navigation menu
course_navigation[enabled] boolean

Set this to enable this feature
course_navigation[text] string

The text that will show on the left-tab in the course navigation
course_navigation[visibility] string

Who will see the navigation tab. “admins” for course admins, “members” for students, null for everyone

Allowed values: admins, members

course_navigation[windowTarget] string

Determines how the navigation tab will be opened. “_blank” Launches the external tool in a new window or tab. “_self” (Default) Launches the external tool in an iframe inside of Canvas.

Allowed values: _blank, _self

course_navigation[default] boolean

Whether the navigation option will show in the course by default or whether the teacher will have to explicitly enable it
course_navigation[display_type] string

The layout type to use when launching the tool. Must be “full_width”, “borderless”, or “default”
editor_button[url] string

The url of the external tool
editor_button[enabled] boolean

Set this to enable this feature
editor_button[icon_url] string

The url of the icon to show in the WYSIWYG editor
editor_button[selection_width] string

The width of the dialog the tool is launched in
editor_button[selection_height] string

The height of the dialog the tool is launched in
editor_button[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit
homework_submission[url] string

The url of the external tool
homework_submission[enabled] boolean

Set this to enable this feature
homework_submission[text] string

The text that will show on the homework submission tab
homework_submission[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit
link_selection[url] string

The url of the external tool
link_selection[enabled] boolean

Set this to enable this feature
link_selection[text] string

The text that will show for the link selection text
link_selection[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit
migration_selection[url] string

The url of the external tool
migration_selection[enabled] boolean

Set this to enable this feature
migration_selection[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit
tool_configuration[url] string

The url of the external tool
tool_configuration[enabled] boolean

Set this to enable this feature
tool_configuration[message_type] string

Set this to ContentItemSelectionRequest to tell the tool to use content-item; otherwise, omit
tool_configuration[prefer_sis_email] boolean

Set this to default the lis_person_contact_email_primary to prefer provisioned sis_email; otherwise, omit
resource_selection[url] string

The url of the external tool
resource_selection[enabled] boolean

Set this to enable this feature
resource_selection[icon_url] string

The url of the icon to show in the module external tool list
resource_selection[selection_width] string

The width of the dialog the tool is launched in
resource_selection[selection_height] string

The height of the dialog the tool is launched in
config_type string

Configuration can be passed in as CC xml instead of using query parameters. If this value is “by_url” or “by_xml” then an xml configuration will be expected in either the “config_xml” or “config_url” parameter. Note that the name parameter overrides the tool name provided in the xml
config_xml string

XML tool configuration, as specified in the CC xml specification. This is required if “config_type” is set to “by_xml”
config_url string

URL where the server can retrieve an XML tool configuration, as specified in the CC xml specification. This is required if “config_type” is set to “by_url”
not_selectable boolean

Default: false, if set to true the tool won't show up in the external tool selection UI in modules and assignments
oauth_compliant boolean

Default: false, if set to true LTI query params will not be copied to the post body.

Example Request:

This would create a tool on this course with two custom fields and a course navigation tab
curl -X POST 'https://<canvas>/api/v1/courses/<course_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \
     -F 'custom_fields[key1]=value1' \
     -F 'custom_fields[key2]=value2' \
     -F 'course_navigation[text]=Course Materials' \
     -F 'course_navigation[default]=false'
     -F 'course_navigation[enabled]=true'

This would create a tool on the account with navigation for the user profile page
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'url=https://example.com/ims/lti' \
     -F 'privacy_level=name_only' \
     -F 'user_navigation[url]=https://example.com/ims/lti/user_endpoint' \
     -F 'user_navigation[text]=Something Cool'
     -F 'user_navigation[enabled]=true'

This would create a tool on the account with configuration pulled from an external URL
curl -X POST 'https://<canvas>/api/v1/accounts/<account_id>/external_tools' \
     -H "Authorization: Bearer <token>" \
     -F 'name=LTI Example' \
     -F 'consumer_key=asdfg' \
     -F 'shared_secret=lkjh' \
     -F 'config_type=by_url' \
     -F 'config_url=https://example.com/ims/lti/tool_config.xml'

Edit an external tool ExternalToolsController#update

PUT /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:PUT|/api/v1/courses/:course_id/external_tools/:external_tool_id

PUT /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:PUT|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Update the specified external tool. Uses same parameters as create

Example Request:

This would update the specified keys on this external tool
curl -X PUT 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>" \
     -F 'name=Public Example' \
     -F 'privacy_level=public'

Delete an external tool ExternalToolsController#destroy

DELETE /api/v1/courses/:course_id/external_tools/:external_tool_id

Scope: url:DELETE|/api/v1/courses/:course_id/external_tools/:external_tool_id

DELETE /api/v1/accounts/:account_id/external_tools/:external_tool_id

Scope: url:DELETE|/api/v1/accounts/:account_id/external_tools/:external_tool_id

Remove the specified external tool

Example Request:

This would delete the specified external tool
curl -X DELETE 'https://<canvas>/api/v1/courses/<course_id>/external_tools/<external_tool_id>' \
     -H "Authorization: Bearer <token>"