Developer Platform (December 2024)

Settings for user accounts

«  Users (user data, whoami)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Accommodations  »

The settings actions let an organization manage the account settings available to users. We’ve divided this functionality into two, general groups:

Attributes

Settings.UpdateLocale

When updating a user’s account setting for preferred locale, pass a structure that looks like this one:

{
    "LocaleId": <number:D2LID>
}
LocaleId

System identifier for a particular Locale.

Custom widget data

Settings.WidgetData

When setting custom widget data, pass a structure that looks like this one:

{
    "Data": <string>
}
Data

Widget data to be stored. Note, this data itself should be in json format. Double quotes within the json string must be escaped with a backslash (”\”) as in this example:

{  "Data": "{ \"key\": \"value\" }"  }

Local authentication security

TWOFACTOR_T

Represents the override setting for adding a two-factor authentication method.

Override Setting

Value

Not Available

0

Optional

1
Settings.LASOverrideData

Returned when obtaining a list of local authentication security overrides.

{
   "UserId": <number:D2LID>,
   "TwoFactor": <number:TWOFACTOR_T>,
   "LocalLogin": <boolean>
}
UserId

User that the override belongs to.

TwoFactor

The override setting for adding a two-factor authentication method.

LocalLogin

Determines whether or not the user is allowed to use local authentication to log in.

Settings.LASOverrideUpdateData

Submitted when updating Local Authentication Security overrides.

{
   "TwoFactor": <number:TWOFACTOR_T>,
   "LocalLogin": <boolean>
}
TwoFactor

The override setting for adding a two-factor authentication method.

LocalLogin

Determines whether or not the user is allowed to use local authentication to log in.

Actions

GET /d2l/api/lp/(version)/accountSettings/mySettings/locale/

Retrieve the current user’s locale account settings.

Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Locale JSON block, containing information about the current user’s currently set locale.

GET /d2l/api/lp/(version)/accountSettings/(userId)/locale/

Retrieve the locale account settings for a particular user.

Parameters:
Oauth2 Scopes:

accountsettings:locale:read

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a Locale JSON block, containing information about the user’s currently set locale.

PUT /d2l/api/lp/(version)/accountSettings/mySettings/locale/

Update the current user’s locale account settings.

Parameters:
JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

PUT /d2l/api/lp/(version)/accountSettings/(userId)/locale/

Update the locale account settings for a particular user.

Parameters:
JSON Parameters:
Oauth2 Scopes:

accountsettings:locale:update

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Custom widget data

These actions let you save a modest amount of data for custom widgets within an org unit, both org-unit wide data, and data specific to individual users. Note the custom widget’s HTML body can gain access to the custom widget’s ID by using the {widgetid} replace string.

Note

Currently, you can only store a modest amount of data for each data record you add. A single widget and org unit combination (as well as a widget, org unit and user combination) has a set data limit and the back-end service does not provide a way to determine how much of the storage has already been used.

DELETE /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)

Delete custom widget data for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

DELETE /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)/mydata

Delete custom widget data for an org unit tied to the current user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

DELETE /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)/(userId)

Delete custom widget data for an org unit tied to a particular user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

Input. The target user identified in the route for this action must have their enrollment role set to be visible within the classlist.

GET /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)

Retrieve custom widget data for an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a WidgetData JSON block showing the widget data for the specified custom widget.

GET /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)/mydata

Retrieve custom widget data for an org unit tied to the current user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a WidgetData JSON block showing the widget data for the specified custom widget.

GET /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)/(userId)

Retrieve custom widget data for an org unit tied to a particular user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

  • userId (D2LID) – User ID.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

Input. Note that the target user identified in the route for this action must have their enrollment role set to be visible within the classlist.

Return. This action returns a WidgetData JSON block showing the widget data for the specified custom widget.

PUT /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)

Update custom data for a widget in an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a WidgetData JSON block showing the widget data for the updated custom widget.

PUT /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)/mydata

Update user-specific custom data for a widget in an org unit.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

JSON Parameters:
Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

  • 1.34- – Obsolete as of LMS v20.24.1.

Return. This action returns a WidgetData JSON block showing the widget data for the updated custom widget.

PUT /d2l/api/lp/(version)/(orgUnitId)/widgetdata/(customWidgetId)/(userId)

Update custom data for a widget for an org unit tied to a particular user.

Parameters:

  • version (D2LVERSION) – API version.

  • orgUnitId (D2LID) – Org unit ID.

  • customWidgetId (D2LID) – Custom widget ID.

  • userId (D2LID) – User ID.

JSON Parameters:

  • CustomWidgetData (Settings.WidgetData) – new JSON config data for spcified user for widget.

Status Codes:
API Versions:

  • 1.43+ – Route first appears in LMS v20.23.5.

  • 1.35-1.42 – Deprecated as of LMS v20.24.1.

Input. Note that the target user identified in the route for this action must have their enrollment role set to be visible within the classlist.

Return. This action returns a WidgetData JSON block showing the widget data for the updated custom widget.

Local authentication security

These actions let you manage overrides to the role permissions within local authentication secrity for individual users. These overrides determine whether a user can configure a two-factor authentication method, or if they can log in using local Brightspace authentication.

DELETE /d2l/api/lp/(version)/localauthenticationsecurity/overrides/

Delete local authentication security overrides for a list of users.

Parameters:
Query Parameters:

  • userIdsCSV (CSV of D2LIDs) – Required. The list of userids to remove overrides for (limited to 100).

Oauth2 Scopes:

localauthenticationsecurity:overrides:manage

Status Codes:
API Versions:

  • 1.45+ – Route first appears in LMS v20.23.11.

GET /d2l/api/lp/(version)/localauthenticationsecurity/overrides/

Retrieve local authentication security overrides for a list of users.

Parameters:
Query Parameters:

  • userIdsCSV (CSV of D2LIDs) – Required. List of user IDs to inquire about (maximum 100).

Oauth2 Scopes:

localauthenticationsecurity:overrides:read

Status Codes:
API Versions:

  • 1.45+ – Route first appears in LMS v20.23.11.

Input. When calling this action, you must provide a list of user IDs for which override information will be returned.

Return. This action returns a JSON array of LASOverrideData JSON blocks showing overrides for the list of users requested. If a user doesn’t exist, they will be omitted from the results.

POST /d2l/api/lp/(version)/localauthenticationsecurity/overrides/

Add or update local authentication security overrides for a list of users.

Parameters:
Query Parameters:

  • userIdsCSV (CSV of D2LIDs) – Required. List of user IDs to manage (maximum 100).

JSON Parameters:
Oauth2 Scopes:

localauthenticationsecurity:overrides:manage

Status Codes:
API Versions:

  • 1.45+ – Route first appears in LMS v20.23.11.

Input. When using this action, you must provide a list of user IDs to manage; all will receive the same local authentication security override policy provided in your LASOVerrideUpdateData JSON block.

Note

Note that two-factor authentication cannot be enabled (TwoFactor value non-zero) if local authentication is not permitted (LocalLogin value is True).

Return. This action does not return any body data.

«  Users (user data, whoami)   ·  [   home  ·   reference  ·   community   |   search  ·   index   ·  routing table   ·  scopes table   ]   ·  Accommodations  »