Names and Role API

API for IMS Names and Role Provisioning Service version 2 .

Official specification: https://www.imsglobal.org/spec/lti-nrps/v2p0

Requires JWT OAuth2 Access Tokens with the https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly scope

Response Content-Type is application/vnd.ims.lti-nrps.v2.membershipcontainer+json

A NamesAndRoleContext object looks like:

// An abbreviated representation of an LTI Context
{
  // LTI Context unique identifier
  "id": "4dde05e8ca1973bcca9bffc13e1548820eee93a3",
  // LTI Context short name or code
  "label": "CS-101",
  // LTI Context full name
  "title": "Computer Science 101"
}

A NamesAndRoleMessage object looks like:

// Additional attributes which would appear in the LTI launch message were this
// member to click the specified resource link (`rlid` query parameter)
{
  // The type of LTI message being described. Always set to
  // 'LtiResourceLinkRequest'
  "https://purl.imsglobal.org/spec/lti/claim/message_type": "LtiResourceLinkRequest",
  // The member's preferred locale
  "locale": "en",
  // The member's API ID
  "https://www.instructure.com/canvas_user_id": 1,
  // The member's primary login username
  "https://www.instructure.com/canvas_user_login_id": "showell@school.edu",
  // Expanded LTI custom parameters that pertain to the member (as opposed to the
  // Context)
  "https://purl.imsglobal.org/spec/lti/claim/custom": {"message_locale":"en","person_address_timezone":"America\/Denver"}
}

A NamesAndRoleMembership object looks like:

// A member of a LTI Context in one or more roles
{
  // Membership state
  "status": "Active",
  // Member's full name. Only included if tool privacy level is `public` or
  // `name_only`.
  "name": "Sienna Howell",
  // URL to the member's avatar. Only included if tool privacy level is `public`.
  "picture": "https://example.instructure.com/images/messages/avatar-50.png",
  // Member's 'first' name. Only included if tool privacy level is `public` or
  // `name_only`.
  "given_name": "Sienna",
  // Member's 'last' name. Only included if tool privacy level is `public` or
  // `name_only`.
  "family_name": "Howell",
  // Member's email address. Only included if tool privacy level is `public` or
  // `email_only`.
  "email": "showell@school.edu",
  // Member's primary SIS identifier. Only included if tool privacy level is
  // `public` or `name_only`.
  "lis_person_sourcedid": "1238.8763.00",
  // Member's unique LTI identifier.
  "user_id": "535fa085f22b4655f48cd5a36a9215f64c062838",
  // Member's roles in the current Context, expressed as LTI/LIS URNs.
  "roles": ["http://purl.imsglobal.org/vocab/lis/v2/membership#Instructor", "http://purl.imsglobal.org/vocab/lis/v2/membership#ContentDeveloper"],
  // Only present when the request specifies a `rlid` query parameter. Contains
  // additional attributes which would appear in the LTI launch message were this
  // member to click the link referenced by the `rlid` query parameter
  "message": [{"https:\/\/purl.imsglobal.org\/spec\/lti\/claim\/message_type":"LtiResourceLinkRequest","locale":"en","https:\/\/www.instructure.com\/canvas_user_id":1,"https:\/\/www.instructure.com\/canvas_user_login_id":"showell@school.edu","https:\/\/purl.imsglobal.org\/spec\/lti\/claim\/custom":{"message_locale":"en","person_address_timezone":"America\/Denver"}}]
}

A NamesAndRoleMemberships object looks like:

{
  // Invocation URL
  "id": "https://example.instructure.com/api/lti/courses/1/names_and_roles?tlid=f91ca4d8-fa84-4a9b-b08e-47d5527416b0",
  // The LTI Context containing the memberships
  "context": {"id":"4dde05e8ca1973bcca9bffc13e1548820eee93a3","label":"CS-101","title":"Computer Science 101"},
  // A list of NamesAndRoleMembership
  "members": [{"status":"Active","name":"Sienna Howell","picture":"https:\/\/example.instructure.com\/images\/messages\/avatar-50.png","given_name":"Sienna","family_name":"Howell","email":"showell@school.edu","lis_person_sourcedid":"1238.8763.00","user_id":"535fa085f22b4655f48cd5a36a9215f64c062838","roles":["http:\/\/purl.imsglobal.org\/vocab\/lis\/v2\/membership#Instructor","http:\/\/purl.imsglobal.org\/vocab\/lis\/v2\/membership#ContentDeveloper"],"message":[{"https:\/\/purl.imsglobal.org\/spec\/lti\/claim\/message_type":"LtiResourceLinkRequest","locale":"en","https:\/\/www.instructure.com\/canvas_user_id":1,"https:\/\/www.instructure.com\/canvas_user_login_id":"showell@school.edu","https:\/\/purl.imsglobal.org\/spec\/lti\/claim\/custom":{"message_locale":"en","person_address_timezone":"America\/Denver"}}]}, {"status":"Active","name":"Terrence Walls","picture":"https:\/\/example.instructure.com\/images\/messages\/avatar-51.png","given_name":"Terrence","family_name":"Walls","email":"twalls@school.edu","lis_person_sourcedid":"5790.3390.11","user_id":"86157096483e6b3a50bfedc6bac902c0b20a824f","roles":["http:\/\/purl.imsglobal.org\/vocab\/lis\/v2\/membership#Learner"],"message":[{"https:\/\/purl.imsglobal.org\/spec\/lti\/claim\/message_type":"LtiResourceLinkRequest","locale":"de","https:\/\/www.instructure.com\/canvas_user_id":2,"https:\/\/www.instructure.com\/canvas_user_login_id":"twalls@school.edu","https:\/\/purl.imsglobal.org\/spec\/lti\/claim\/custom":{"message_locale":"en","person_address_timezone":"Europe\/Berlin"}}]}]
}

List Course Memberships Lti::Ims::NamesAndRolesController#course_index

GET /api/lti/courses/:course_id/names_and_roles

Scope: url:GET|/api/lti/courses/:course_id/names_and_roles

Return active NamesAndRoleMemberships in the given course.

Request Parameters:

Parameter Type Description
rlid string

If specified only NamesAndRoleMemberships with access to the LTI link references by this ‘rlid` will be included. Also causes the member array to be included for each returned NamesAndRoleMembership. If the `role` parameter is also present, it will be ’and-ed’ together with this parameter

role string

If specified only NamesAndRoleMemberships having this role in the given Course will be included. Value must be a fully-qualified LTI/LIS role URN. If the ‘rlid` parameter is also present, it will be ’and-ed’ together with this parameter

limit string

May be used to limit the number of NamesAndRoleMemberships returned in a page. Defaults to 50.

Returns a NamesAndRoleMemberships object

List Group Memberships Lti::Ims::NamesAndRolesController#group_index

GET /api/lti/groups/:group_id/names_and_roles

Scope: url:GET|/api/lti/groups/:group_id/names_and_roles

Return active NamesAndRoleMemberships in the given group.

Request Parameters:

Parameter Type Description
`rlid` string

If specified only NamesAndRoleMemberships with access to the LTI link references by this ‘rlid` will be included. Also causes the member array to be included for each returned NamesAndRoleMembership. If the role parameter is also present, it will be ’and-ed’ together with this parameter

role string

If specified only NamesAndRoleMemberships having this role in the given Group will be included. Value must be a fully-qualified LTI/LIS role URN. Further, only purl.imsglobal.org/vocab/lis/v2/membership#Member and purl.imsglobal.org/vocab/lis/v2/membership#Manager are supported. If the ‘rlid` parameter is also present, it will be ’and-ed’ together with this parameter

limit string

May be used to limit the number of NamesAndRoleMemberships returned in a page. Defaults to 50.

Returns a NamesAndRoleMemberships object