Developer Platform (July 2020)

LTI Advantage management (registrations, deployments, and links)

«  Assessments and rubrics   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  LTI management (links and tool providers)  »

Contents

The LTI actions let an organization manage the LTI registrations, deployments, and links available to particular organization units. Callers can use these routes to fetch, register, deploy, update, and remove entries for LTI tools and LTI links. Note that each created LTI link will have a unique D2LID assigned so you can identify a link independently of the org unit with which it’s registered; however, you cannot register a single LTI link with more than one org unit. Registrations and deployments can only be created at the organization. These routes apply to LTI 1.3+ only.

Note

These structures and routes apply only to LTI Advantage (LTI v1.3+). You can also refer to the reference for legacy LTI support (LTI v1.1.x). The LTI API routes are fulfilled by the LE product component and included in the LE API contract version. The ‘lti’ product component listed in version blocks (such as Version.ProductVersions) indicates the level of LTI standard the platform supports, and not the API contract version for these routes.

Attributes

EXTENSION_T

LTI Advantage extensions can have values of a variety of data types; we use the term EXTENSION_T to stand in for an appropriate integer value:

Data type name

Value

AssignmentAndGradeServices

1

DeepLinking

2

NamesAndRoleProvisioningServices

3
LINK_TYPE_T

LTI Advantage Link types can have values of a variety of data types; we use the term LINK_TYPE_T to stand in for an appropriate integer value:

Data type name

Value

Basic

1

Widget

2

Quicklink

3

InsertStuff

4

Tool Registration

LTI.CreateRegistrationData

When a client invokes an action to register or update an already registered LTI tool for an organization, it should provide a structure like this:

{
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "Domain": <string>,
    "RedirectUrls": [ <string>, ... ],
    "OpenIDConnectLoginUrl": <string>,
    "KeysetUrl": null|<string>,
    "EnabledExtensions": [ <number:EXTENSION_T>, ... ],
    "SendInstitutionRole": <boolean>,
    "CustomParameters": [ { <composite:LTI.CustomParameters> }, ... ]  // Added with LE API v1.46
}
CustomParameters

With LE API v1.46 and later, you pass any custom parameters as name-value pairs in this required property; if you need no custom parameters for this LTI link, you should provide an empty array. Supported custom parameters will show as Substitution Parameters in Brightspace.

With LE API v1.45 and earlier, you may not provide this property.

LTI.RegistrationData

When a client invokes an action that would retrieve the registration information for an LTI tool, the Learning Service sends back a structure like this:

{
    "ClientId": <GUID>,
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "Domain": <string>,
    "RedirectUrls": [ <string>, ... ],
    "OpenIDConnectLoginUrl": <string>,
    "KeysetUrl": <string>,
    "EnabledExtensions": [ <number:EXTENSION_T>, ... ],
    "SendInstitutionRole": <boolean>,
    "BrightspaceAudience": <string>,
    "BrightspaceIssuer": <string>,
    "BrightspaceKeysetURL": <string>,
    "BrightspaceOAuth2AccessTokenURL": <string>,
    "BrightspaceOIDCAuthenticationEndpoint": <string>,
    "CustomParameters": [ { <composite:LTI.CustomParameters> }, ... ]  // Added with LE API v1.46
}
Brightspace* properties

All the Brightspace* properties are Brightspace values that should be shared back to the tool.

Tool Deployment

LTI.CreateDeploymentData

When a client invokes an action to deploy or update an already deployed LTI tool for an organization, it should provide a structure like this:

{
    "ClientId": <GUID>,
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "EnabledExtensions": [ <number:EXTENSION_T>, ... ],
    "Anonymous": <boolean>,
    "SendOrgUnitInformation": <boolean>,
    "SendUserFirstName": <boolean>,
    "SendUserMiddleName": <boolean>,
    "SendUserLastName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendD2LUserId": <boolean>,
    "SendD2LUsername": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "PreProvisioning": <boolean>,
    "CustomParameters": [ { <composite:LTI.CustomParameters> }, ... ]  // Added with LE API v1.46
}
PreProvisioning

Security setting to send classlist including users not known to tool.

CustomParameters

With LE API v1.46 and later, you pass any custom parameters as name-value pairs in this required property; if you need no custom parameters for this LTI link, you should provide an empty array. Supported custom parameters will show as Substitution Parameters in Brightspace.

With LE API v1.45 and earlier, you may not provide this property.

LTI.DeploymentData

When a client invokes an action that would retrieve the deployment information for an LTI tool, the Learning Service sends back a structure like this:

{
    "DeploymentId": <GUID>,
    "ClientId": <GUID>,
    "IsEnabled": <boolean>,
    "Name": <string>,
    "Description": null|<string>,
    "EnabledExtensions ": [ <number:EXTENSION_T>, ... ],
    "AvailableExtensions": [ <number:EXTENSION_T>, ... ],
    "Anonymous": <boolean>,
    "SendOrgUnitInformation": <boolean>,
    "SendUserFirstName": <boolean>,
    "SendUserMiddleName": <boolean>,
    "SendUserLastName": <boolean>,
    "SendUserEmail": <boolean>,
    "SendD2LUserId": <boolean>,
    "SendD2LUsername": <boolean>,
    "SendD2LOrgDefinedId": <boolean>,
    "SendLinkTitle": <boolean>,
    "SendLinkDescription": <boolean>,
    "PreProvisioning": <boolean>,
    "IsAvailable": <boolean>,
    "CustomParameters": [ { <composite:LTI.CustomParameters> }, ... ]  // Added with LE API v1.46
}
PreProvisioning

Security setting to send classlist including users not known to tool.

AvailableExtensions, EnableExtensions

For an extension to be active it must be in both the AvailableExtensions and EnabledExtensions lists.

Tool Deployment Sharing

LTI.CreateSharingRuleData

When a client invokes an create a sharing rule that will make an LTI Deployment available to an org unit they should send this structure:

{
    "SharingOrgUnitId":  <number:D2LID>,
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>
}
LTI.UpdateSharingRuleData

When a client invokes an update a sharing rule that will make an LTI Deployment available to an org unit they should send this structure:

{
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>
}
LTI.OrgUnitSharingRuleData

When a client invokes an action to retrieve the sharing information for an already registered LTI Deployment they will receive this structure:

{
    "SharingOrgUnitId":  <number:D2LID>,
    "ShareWithOrgUnit": <boolean>,
    "ShareWithDescendants": <boolean>,
    "Inherited": null|<boolean>
}
Inherited

Determines if an org unit has been shared to by having a parent that is shared with all descendants.

Migration

LTI.MigrationData

When a client invokes an action to migrate a 1.1 LTI link to an LTI Advantage link, they should send this structure:

{
    "DeploymentId":  <GUID>,
    "ToolProviderId": <number:D2LID>|null,
}
ToolProviderId

A null ToolProviderId should be used when the LTI link has its own key and secret used for signing during launch. ToolProviderId can also be left null when migrating remote plugins as the tool provider linked to the remote plugin will be used by default.

Actions

Tool Registration

DELETE /d2l/api/le/(version)/ltiadvantage/registration/(clientId)

Remove an LTI Advantage registration.

Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Note

A registration may only be deleted if it is not tied to any deployments.

GET /d2l/api/le/(version)/ltiadvantage/registration/

Retrieve the information for all LTI registrations for the organization.

Parameters
Query Parameters

  • isEnabled (boolean) – Optional. Used to limit registrations based on IsEnabled status.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of registrations belonging to the organization.

GET /d2l/api/le/(version)/ltiadvantage/registration/(clientId)

Retrieve the information for a particular LTI registration.

Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Registration JSON block containing the data associated with the matching LTI registration.

POST /d2l/api/le/(version)/ltiadvantage/registration/

Register a new LTI tool for the organization.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Registration JSON block containing the data associated with the newly created LTI registratation.

PUT /d2l/api/le/(version)/ltiadvantage/registration/(clientId)

Update the information associated with an LTI tool registration.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Registration JSON block containing the updated data for the tool registration.

Tool Deployment

DELETE /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)

Remove an LTI Advantage deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Note

A LTI tool deployment may only be deleted if it is not tied to any links.

GET /d2l/api/le/(version)/ltiadvantage/deployment/

Retrieve the information for all LTI deployments for the organization.

Parameters
Query Parameters

  • clientId (D2LID) – Optional. Used to limit deployments based on ClientId value.

  • isEnabled (boolean) – Optional. Used to limit deployments based on IsEnabled status.

  • isAvailable (boolean) – Optional. Used to limit deployments based on IsAvailable status.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of LTI tool deployments belonging to the organization.

GET /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)

Retrieve the information for a particular LTI tool deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Deployment JSON block containing the data associated with the matching LTI tool deployment.

POST /d2l/api/le/(version)/ltiadvantage/deployment/

Create a new LTI tool deployment for the organization.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Deployment JSON block containing the data associated with the newly created LTI tool deployment.

PUT /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)

Update the information associated with an LTI tool deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Deployment JSON block containing the updated data for the LTI tool deployment.

Tool Deployment Sharing

DELETE /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/

Delete all sharing rules for a particular LTI deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

DELETE /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/(sharingOrgUnitId)

Delete the sharing rule for a particular org unit and LTI deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

  • sharingOrgUnitId (D2LID) – Org unit ID the deployment is shared to.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

GET /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/

Retrieve the sharing rules for a particular LTI deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

Query Parameters

  • incldueInherited (boolean) – Optional. Used to include org units shared by inheritence.

  • orgUnitId (D2LID) – Optional. Used to limit to a single org unit.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of OrgUnitSharingRuleData for the deployment.

POST /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/

Add a sharing rule for a particular LTI deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a CreateSharingRuleData JSON block containing the data associated with the newly registered sharing rule.

PUT /d2l/api/le/(version)/ltiadvantage/deployment/(deploymentId)/sharing/(sharingOrgUnitId)

Update the sharing rule for a particular org unit and LTI tool deployment.

Parameters

  • version (D2LVERSION) – API version.

  • deploymentId (D2LID) – Deployment ID.

  • sharingOrgUnitId (D2LID) – Org unit ID the deployment is shared to.

JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a CreateSharingRuleData JSON block containing the data associated with the newly updated sharing rule.

Links

DELETE /d2l/api/le/(version)/ltiadvantage/links/orgunit/(orgUnitId)/(linkId)

Remove an LTI Advantage link.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org Unit ID.

  • linkId (D2LID) – Link ID.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

GET /d2l/api/le/(version)/ltiadvantage/links/organization/

Retrieve the information for all LTI Advantage links for the organization.

Parameters
Query Parameters

  • deploymentId (GUID) – Optional. Used to limit links based on deployment.

  • isEnabled (boolean) – Optional. Used to limit links based on IsEnabled status.

  • IsAvailable (boolean) – Optional. Used to limit links based on IsAvailable status.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of Links belonging to the organization.

GET /d2l/api/le/(version)/ltiadvantage/links/organization/(linkId)

Retrieve the information for a particular LTI Advantage organization link.

Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the matching LTI Advantage link.

GET /d2l/api/le/(version)/ltiadvantage/links/orgunit/(orgUnitId)/

Retrieve the information for all LTI Advantage links within the scope of an org unit.

Parameters

  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

Query Parameters

  • deploymentId (GUID) – Optional. Used to limit links based on deployment.

  • isEnabled (boolean) – Optional. Used to limit links based on IsEnabled status.

  • IsAvailable (boolean) – Optional. Used to limit links based on IsAvailable status.

Status Codes

  • 200 OK – Action succeeded.

  • 403 Forbidden – No permission to manage external learning tool links or create external learning tool links from external learning tool providers or create quicklinks from available external learning tools links.

  • 429 Too Many Requests – API call-rate limit exceeded.

API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns an ObjectListPage JSON block containing a list of Links belonging to the org unit.

GET /d2l/api/le/(version)/ltiadvantage/links/orgunit/(orgUnitId)/(linkId)

Retrieve the information for a particular LTI Advantage link.

Parameters

  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

  • linkId (D2LID) – Link ID.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the matching LTI Advantage link.

POST /d2l/api/le/(version)/ltiadvantage/links/organization/

Create a new LTI Advantage link for the organization.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the newly created LTI Advantage link.

POST /d2l/api/le/(version)/ltiadvantage/links/orgunit/(orgUnitId)/

Create a new LTI Advantage link for an org unit.

Parameters

  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the data associated with the newly created LTI Advantage link.

POST /d2l/api/le/(apiVersion)/ltiadvantage/quicklinks/orgunit/(orgUnitId)/link/(linkId)

Build a new quicklink around an existing LTI Advantage link.

Parameters

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • linkId (D2LID) – Link ID.

Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Input. Provide an empty post body.

Return. This action returns a Quicklink JSON block containing the details for the new quicklink.

PUT /d2l/api/le/(version)/ltiadvantage/links/organization/(linkId)

Update the information associated with an LTI Advantage link.

Parameters
JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the updated data for the LTI Advantage link.

PUT /d2l/api/le/(version)/ltiadvantage/links/orgunit/(orgUnitId)/(linkId)

Update the information associated with an LTI Advantage link.

Parameters

  • version (D2LVERSION) – API version.

  • version – Org Unit ID.

  • linkId (D2LID) – Link ID.

JSON Parameters
Status Codes
API Versions

  • 1.40+ – Route first appears in LMS v20.19.12.

Return. This action returns a Link JSON block containing the updated data for the LTI Advantage link.

Migration

POST /d2l/api/le/(version)/ltiadvantage/migration/links/(linkId)

Migrate a legacy LTI link to an LTI Advantage link.

Parameters
JSON Parameters

  • MigrationData (MigrationData) – Migration directions for link.

Status Codes
API Versions

  • 1.46+ – Route first appears in LMS v20.20.07.

Input. The action’s body should be a MigrationData JSON data block.

Return. This action returns an empty body.

Note

Before migrating a link from legacy LTI to LTI Advantage, you should verify with the respective LTI Tool that it will properly support the link after migration.

«  Assessments and rubrics   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  LTI management (links and tool providers)  »