The Permissions actions let an organization manage the permissions and capabililties assigned to users within the context of particular tools, org units, and roles.

Permissions. The API refers to each distinct permission for each tool in the back-end service as a permission claim; for example, “Manage Own Profile” is the permission claim that determines whether a user has the right to manage his or her own profile information.

The permission grant, the context within which a user can be granted permission for a claim, is an intersection between the claim itself, an org unit type, and a role. For example, users enrolled in the Student role in the root organization org unit type, may or may not be granted permission to manage their own profiles.

A permission grant can have one of two allowance state values: “allowed” or “not allowed”. If the permission grant is set to “allowed”, then the user within that context has permission to take that action; if set to “not allowed”, then user within that context explicitly does not have permission to take that action.

Capabilities. Unlike permissions, which express simply a “thing that a user can or cannot do”, capabilities express things that a user (role) can do with another user (role) as a target. An example in the back-end service’s web UI would be Impersonation – Brightspace allows administrators to declare that users with Role X can do something that involves Role Y within the context of a particular org unit: for example, that an Instructor role can impersonate a Student role within course offering org units. Another example is the capability to “search for” a user role within an org unit: this governs some activities where a user asks to “see a list of users” also enrolled within a context.

Attributes ¶

Permissions.Capability¶

{
    "CapabilityId": <string>,   // Appears only on read actions
    "Name": <string>,
    "ActorRoleId": <number:D2LID>,
    "TargetRoleId": <number:D2LID>,
    "OrgUnitTypeId": <number:D2LID>
}

CapabilityId

Not that when you see this structure sent to you from the back-end service, it includes a capability ID; when you provide a capability structure in to the service, you should omit this property.

ActorRoleId and TargetRoleId

The actor role is the enrollment role of the user context making the API call.

The target role is the enrollment role grouping together users that the actor role could affect.

OrgUnitTypeId

A single capability binding only pertains within the scope of this type of org unit.

Permissions.ClaimGrant¶

{
    "GrantId": <string>,
    "ClaimId": <string>,
    "RoleId": <number:D2LID>,
    "OrgUnitTypeId": <number:D2LID>,
    "Allowed": <boolean>
}

Permissions.ClaimMetaData¶

{
    "ClaimId": <string>,
    "DisplayName": <string>
}

Actions ¶

DELETE /d2l/api/lp/(version)/permissions/tools/(toolId)/capabilities/(capabilityId)¶

Remove the specified capability.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.
capabilityId (String) – Capability ID.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to change allowance state for capability grants.
404 Not Found – No such tool, or no such capability.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.4.10.

DELETE /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/allowed/(grantId)¶

Reset a permission grant to “not allowed”.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.
grantId (String) – Permission grant ID.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to change allowance state for permission grants.
404 Not Found – No such tool, or no such permission grant.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

GET /d2l/api/lp/(version)/permissions/tools/(toolId)/capabilities/¶

Retrieve all the capability grants for a tool.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.

Query Parameters:

name (String) – Optional. Filter capabilties to only those matching this name.
actorRoleId (D2LID) – Optional. Filter capabilties to only those offered to this role.
targetRoleId (D2LID) – Optional. Filter capabilities to only those acting on this role.
orgUnitTypeId (D2LID) – Optional. Filter capabilities to only those applying in this org unit type.
bookmark – Optional. Bookmark to use for fetching next data set segment.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see capability grants.
404 Not Found – No such tool.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.4.10.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

You can use a variety of filter query parameters to narrow the result set to those entires that match the associated filters. If you provide more than one filter query parameter, they will all apply to narrow the results.

Return. This action returns a paged result set containing the resulting Capability data blocks for the segment following your bookmarket parameter (for the first segment, if the bookmark is empty or missing).

GET /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/¶

Retrieve all the permission grants for a tool’s permissions claims.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.

Query Parameters:

claimId (D2LID) – Optional. Filter grants to those for identified claim only.
roleId (D2LID) – Optional. Filter grants for identified role only.
orgUnitTypeId (D2LID) – Optional. Filter grants for identified org unit type only.
bookmark – Optional. Bookmark to use for fetching next data set segment.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see permission grants.
404 Not Found – No such tool.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting allowed and not-allowed ClaimGrant data blocks for the segment following your bookmarket parameter (for the first segment, if the bookmark is empty or missing).

GET /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/allowed/¶

Retrieve all the allowed permission grants for a tool for a tool’s permissions claims.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.

Query Parameters:

claimId (D2LID) – Optional. Filter grants to those for identified claim only.
roleId (D2LID) – Optional. Filter grants for identified role only.
orgUnitTypeId (D2LID) – Optional. Filter grants for identified org unit type only.
bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see permission grants.
404 Not Found – No such tool.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

You can use a variety of filter query parameters to further narrow the result set to those log entires that match the associated filters. If you provide more than one filter query parameter, they will all apply to narrow the results.

Return. This action returns a paged result set containing the resulting allowed ClaimGrant data blocks for the segment following your bookmarket parameter (for the first segment, if the bookmark is empty or missing).

GET /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/allowed/(grantId)¶

Determine the allowance state of a permission grant.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.
grantId (String) – Permission grant ID.

Status Codes:

200 OK – Action succeeded: permission grant is set to “allowed”.
403 Forbidden – No permission to see permission grants.
404 Not Found – No such tool, or no such grant, or grant is set to “not allowed”.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

GET /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/metadata/¶

Retrieve the meta-data for all of a tool’s permission claims.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.

Query Parameters:

bookmark (string) – Optional. Bookmark to use for fetching next data set segment.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see permission claim meta-data.
404 Not Found – No such tool.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

Input. You can use a bookmark query parameter as a paging offset, to indicate that the service should return the segment of results immediately following your bookmark.

Return. This action returns a paged result set containing the resulting ClaimMetaData data blocks for the segment following your bookmark parameter (or the first segment, if the bookmark is empty or missing).

GET /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/metadata/(claimId)¶

Retrieve the meta-data for one of a tool’s permission claims.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.
claimId (String) – Permission claim ID.

Status Codes:

200 OK – Action succeeded.
403 Forbidden – No permission to see permission claim meta-data.
404 Not Found – No such tool, or no such permission claim.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

Return. This action returns a ClaimMetaData JSON block containing the meta-data for the indicated permission claim.

POST /d2l/api/lp/(version)/permissions/tools/(toolId)/capabilities/¶

Grant a tool capability.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.

JSON Parameters:

Capability (Permissions.Capability) – Capability to grant.

Status Codes:

200 OK – Action succeeded.
400 Bad Request – Invalid capability provided.
403 Forbidden – No permission to grant capability.
404 Not Found – No such tool.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.4.10.

Return. Upon success, this action returns a Capability JSON block containing the meta-data for the new tool capability granted.

PUT /d2l/api/lp/(version)/permissions/tools/(toolId)/claims/allowed/(grantId)¶

Set a permission grant to “allowed”.

Parameters:

version (D2LVERSION) – API version.
toolId (String) – Tool ID.
grantId (String) – Permission grant ID.

Status Codes:

200 OK – Action succeeded.
400 Bad Request – No such grant.
403 Forbidden – No permission to change allowance state for permission grants.
404 Not Found – No such tool.
429 Too Many Requests – API call-rate limit exceeded.

API Versions:

unstable – Route first appears in LMS v10.3.0.

Input. Provide an empty post body. You should ensure that your request includes a Content-Length: 0 HTTP header value (some HTTP client libraries may neglect to do this with empty post calls).

Developer Platform (April 2024)

Permissions

Attributes¶

Actions¶

Attributes ¶

Actions ¶