LearningStudio uses OAuth to control access to the REST API. OAuth uses tokens and signature blocks to authenticate each API request to minimize the need to send login credentials (for example, usernames and passwords) across the Internet. You must include the appropriate authentication data in the request header for each API request; otherwise, LearningStudio will deny the request.
The REST API uses OAuth in two ways:
- OAuth 1.0a is used for system-to-system calls where a user context is not accessed (i.e., you don't need to access data as a user nor create data tied to that user such as thread post). In these requests, every API call must include your Application ID, Token Key Moniker, and Shared Secret.
- OAuth 2.0 is used when accessing or modifying user-specific data, such as making a thread post on behalf of a user or retrieving a user’s recent activity. In these requests, you will first use the API keys to generate a token, and then include that token with every API call.
There are two types of keys used with the REST APIs. The first is your Application ID which is used to identify your application. If you are a third party developer or EdTech software vendor, you will always use the same Application ID across all LearningStudio campuses.
Secondly, each LearningStudio campus has its own campus keys, which are called the Token Key Moniker and Shared Secret. These control access to the user and course data for each LearningStudio instance. If you are a third party developer or EdTech software vendor, you will need a different set of campus keys for every LearningStudio customer to integrate with.
See Get a Key for more information on how to obtain these keys.
Important: You must keep these authentication credentials secure and restricted. If your credentials ever become known outside of your authorized systems, your transactions with the LearningStudio API and an institution's data may be compromised. Compromised keys will be immediately terminated.
Important: Every distinct application you build should have its own Application ID; do not share your this key. Application IDs have a per-key quota limit; sharing the key can inadvertently trip the quota limit and limit your app's ability to use the APIs.
Decide Between OAuth 1.0a and OAuth 2.0
This protocol should be used when building system-to-system functionality, such as administrative applications, third party gradebook interaction, course status, etc. System-to-System functionality is not bounded by user-level restrictions and/or is outside of user-related context. For example, OAuth 1.0a allows access to course information without the context of a user. It also allows access to user data and resources anywhere within the Educational Partner. To use OAuth 1.0, you only need your Application ID and the appropriate campus keys; specific user information is not required.
Not all APIs are compatible with OAuth 1.0, because some require a user's context (e.g., writing a thread post). Also, you should use care not to display data (like course content) that users do not have access to. When retrieving information you will display to users, use OAuth 2.
For instructions to implement this protocol, see OAuth 1.0a.
This protocol should be used when user-level access to protected data and resources is needed. Access is provided within the context of the provided user and is bounded by the rights and restrictions for that user. For example, a user can access his or her own personal data and data for a course in which the user is enrolled, but cannot access data or resources for a course in which the user is not enrolled. To use the OAuth 2.0 protocol, you must provide your Application ID and know either the user's username and password, or combine their username with the appropriate campus keys.
For instructions to implement this protocol, see OAuth 2.0.
OAuth Protocol Use Case Comparison
|Use Case||OAuth 1.0a||OAuth 2.0|
|An administrative web application developed by the Educational Partner||Yes|
|A native mobile application||Yes|
|A third party web application deployed by the Educational Partner||Yes|
|A user widget for the Educational Partner's portal web application||Yes|
OAuth Terminology Comparison
The OAuth 1.0a and 2.0 standards use different terminology for the same keys. For consistency and clarity in our documentation, we only refer to the keys by a single name. Here's how our terminology compares to the standard:
|Authorization Credential||Our Terminology||OAuth 1.0a||OAuth 2.0|
|Identifier for the application making the request||Application ID||Application ID||Client ID|
|Public encryption key for the LearningStudio campus||Token Key Moniker||Consumer Key||Token Key Moniker (or just Key Moniker)|
|Private encryption key for the LearningStudio Campus||Shared Secret||Consumer Secret||Shared Secret (or Secret Key)|
|User's Username||Username or Login ID||N/A||Username|
|Identifier for a LearningStudio Campus (used in OAuth 2 Password Grant Type)||Client String||N/A||N/A|