Pearson
Always Learning

Overview

You can request OAuth 2.0 tokens for the designated user using one of the following authentication protocols:

  • OAuth 2.0 Password, Initial Authentication - Request both the Access Token and the Refresh Token.
  • OAuth 2.0 Password, Refresh Token - Request a new set of Access Token and Refresh Token using a valid Refresh Token from a previous authentication request.
  • OAuth 2.0 Assertion, Authentication - Request a new set of Access Token and Refresh Token using a valid Refresh Token from a previous authentication request.

You control which request is being made by providing the appropriate information in the request body of the URI request. In this description, it is assumed that you have already gathered and/or generated the required information, such as the username and password, or the username and assertion string with signature.

After you receive the authentication tokens, you will add them to the request header of every subsequent URI request to authorize each transaction for the user.

Caution: You must not locally store, save, or cache the user credentials (username and password) because this action can cause a high security risk. Violating this policy can result in immediate termination of your authorization to use the LearningStudio APIs.

You can store the username alone without violating this policy.

See the following links for more information:

Supported Role Types: Professor, Teaching Assistant, Student

Supported Authorization Protocols: OAuth 2.0 - Password, OAuth 2.0 - Assertion

HTTP Verb Descriptions

HTTP Verb Description
POST

Request a new access token. If using the OAuth 2.0 Password protocol, also request a new refresh token.

API Routes/Parameters

/token

Route/Resource Parameters

None.

Request Header

Content-Type: application/x-www-form-urlencoded

Request Body

The Request Body differs depending on the type of authentication token(s) being requested.

Request Body - Password, Initial Authentication

Use this request body to request the set of Access Token and Refresh Token when the user initially logs in and provides the username and password.

grant_type={grantType}&client_id={applicationId}&username={clientString}\{username}&password={password}

Request Body Parameters

Name Description Valid Values Required?
{grantType} Designates the type of token request. password Yes
{applicationId} Application ID that is submitting the password authentication request on behalf of the user. Yes
{clientString} Educational Partner client string. Yes
{username} Educational Partner username. Yes
{password} Password for the user. Yes

Request Body - Password, Refresh Token

Use this request body when you use the Refresh Token to request a new set of Access Token and Refresh Token.

grant_type={grantType}&client_id={applicationId}&refresh_token={refreshToken}

Request Body Parameters

Name Description Valid Values Required?
{grantType} Designates the type of token request. refresh_token Yes
{applicationId} Application ID that is submitting the refresh token request on behalf of the user. Yes
{refreshToken} Refresh token from previous authentication. Yes

Request Body - Assertion, Authentication

Use this request body to request an Access Token when you use the OAuth 2.0 - Assertion protocol. You must have previously built the assertion string and generated the signature using the process described in the Create OAuth 2.0 Assertion Request use case.

Note: Parameter values must be URL encoded (for example, a colon (:) must be encoded as %3a).

Using login_id as the username:

grant_type={grantType}&assertion_type={assertionType}&assertion={clientName}%7c{keyMoniker}%7c{applicationId}%7c{clientString}%7c{username}%7c{signatureDateTime}%7c{assertionSignature}

Using sourced_id as the username:

grant_type={grantType}&assertion_type={assertionType}&assertion={applicationName}%7c{keyMoniker}%7c{applicationId}%7c{clientString}%7c{source}%3a{sourcedId}%7c{signatureDateTime}%7c{assertionSignature}

Request Body Parameters


Name Description Valid Values Required?
{grantType} Designates the type of token request. assertion Yes
{assertionType} Designates whether assertion is using the Educational Partner username or the Education Partner sourced ID.
  • urn%3aecollege%3anames%3amoauth%3a1.0%3aassertion - Assertion is using the Educational Partner username to identify the user. (Decoded value urn:ecollege:names:moauth:1.0:assertion)
  • urn%3aecollege%3anames%3asourcedid%3a1.0%3aassertion - Assertion is using the Educational Partner sourced ID to identify the user. (Decoded value urn:ecollege:names:sourcedid:1.0:assertion)
Yes
{applicationName} Application name that is submitting the assertion authentication request on behalf of the user. Yes
{keyMoniker} Educational Partner public key. Yes
{applicationId} Application ID that is submitting the assertion authentication reset request on behalf of the user. Yes
{clientString} Educational Partner client string. Yes if {assertionType} = urn%3aecollege%3anames%3amoauth%3a1.0%3aassertion
{username} Educational Partner username from login ID. Yes if {assertionType} = urn%3aecollege%3anames%3amoauth%3a1.0%3aassertion
{source} Educational Partner source value. Yes if {assertionType} = urn%3aecollege%3anames%3asourcedid%3a1.0%3aassertion
{sourceId} Educational Partner user sourced ID. Yes if {assertionType} = urn%3aecollege%3anames%3asourcedid%3a1.0%3aassertion
{signatureDateTime} Date and time used to generated the signature hash. Format is YYYY-MM-DDTHH%3aMM%3aSSZ (decoded value - YYYY-MM-DDTHH:MM:SSZ). Time is in UTC (no offset). Yes
{assertionSignature} Signature hash value that was generated specifically for this request. Yes

Response Header

Content-Type: application/{format}; charset=utf-8

Response Header Parameters

Name Description
{format} Format of response data.

Response Body

The response body differs depending on the type of OAuth 2.0 authentication that was requested.

Response Body - Password, Initial Authentication and Refresh Token

{
    "refresh_token":"{refreshToken}",
    "access_token":"{accessToken}",
    "expires_in":"{expiresInSeconds}"
}

Response Body Parameters

Name Description
{refreshToken} Refresh token that can be used to request a new set of Access Token and Refresh Token for the user.
{accessToken} Access token that is included in every API request to authorize the transaction for the user.
{expiresInSeconds} Number of seconds until the Access Token and Refresh Token become invalid.

Response Body - Assertion, Authentication

{
    "access_token":"{accessToken}",
    "expires_in":"{expiresInSeconds}"
}

Response Body Parameters

Name Description
{AccessToken} Access token that is included in every API request to authorize the transaction for the user.
{expiresInSeconds} Number of seconds until the Access Token becomes invalid.

Response HTTP Codes

See Response HTTP Status Codes for an overview description of the HTTP response status codes in the LearningStudio APIs.

Examples

OAuth 2.0 Password Authentication Request

Request

POST http://{domain}/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=password&client_id=30bb1d4f-2677-45d1-be13-331234404402&username=epstring\jsmith&password=mypassword

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 13 Jun 2013 17:44:59 GMT
 
{
  "refresh_token":"30bb1d4f-2677-45d1-be13-339171234402|b7aa4e1f-733e-40e2-a546-a93cf6426ee9|2121372|2013-06-13T12%3a54%3a59|21e3127c9c57fa4bc595ece704b88572",
  "access_token":"30bb1d4f-2677-45d1-be13-312374404402|da3e64c4-05d1-44d6-bcf7-cac945f2fd6d|2121372|2013-06-13T12%3a44%3a59|e11cb25ec6117bd64cd6a01f28b44b90",
  "expires_in":3600
}

OAuth 2.0 Assertion Authentication Request

Request

POST https://{domain}/token
Content-Type: application/x-www-form-urlencoded
grant_type=assertion&assertion_type=urn%3aecollege%3anames%3amoauth%3a1.0%3aassertion&assertion=PublicU_Portal%7c123456%7c936DA034-9ABD-4d9d-80C7-02AF85C8D2A8%7cpublicU%7jsmith%7c2011-05-11T03%3a24%3a24Z%7c8b4c7123e4699fde93d6f88c8aae1d53

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Thu, 27 Jun 2013 21:20:37 GMT
{
  "refresh_token":"c8b4c7123e4699fde93d6f88c8aae1d53|b7aa4e1f-733e-40e2-a546-a93cf6426ee9|2121372|2013-06-13T12%3a54%3a59|21e3127c9c57fa4bc595ece704b88572",
  "access_token":"c8b4c7123e4699fde93d6f88c8aae1d53|da3e64c4-05d1-44d6-bcf7-cac945f2fd6d|2121372|2013-06-13T12%3a44%3a59|e11cb25ec6117bd64cd6a01f28b44b90",
  "expires_in":3600
}

2602 reads
Always Learning
Pearson