Pearson
Always Learning

Overview

Using the OAuth 2.0 protocol, the Authentication process will provide an Access Token. You must include the Access Token for a user in a X-Authorization HTTP header for all subsequent API requests to authorize the API call. LearningStudio will deny the request if you do not include the correct Access Token, if the token has expired, or if the user the token identifies is not allowed to access the data.


Libraries & Sample Code

Reading the documentation is wise to better understand how to use an Access Token in a request. To make implementation easier, we have the LearningStudio Libraries that can execute API requests and handle authentication for you. If you want to roll your own code, check out the OAuth 2 sample code for working examples.


Access Token Syntax

The access token generated by LearningStudio and returned to the application has the following syntax:

{applicationId}|{consumerKey}|{userId}|{tokenExpirationTimestamp)}|{requestCmacSignature}

Access Token Parameters

Name Description
{applicationId} ID of the application that made the authentication request.
{consumerKey} Educational Partner consumer key (also called "key moniker" or "public key").
{userId} LearningStudio user ID.
{tokenExpirationTimestamp)} Date and time when the access token will expire. Format is YYYY-MM-DDTHH:MM:SS in Mountain Standard Time (UTC -7:00).
{requestCmacSignature} Signature hash created by LearningStudio for the API request.

Using Access Token in API Request

Currently, you can use either of two ways to include the access token in a subsequent API request:

Access Token in HTTP Header

This method embeds the access token in the request header for each API call. Following is a sample:

GET https://{domain}/me HTTP/1.1 X-Authorization: Access_Token access_token=ajlakdsjflkasdfh8vab372iu345h3

Access Token in Cookie

This method sends the the access token stored inside a cookie. You must handle creating the cookie; LearningStudio APIs will not automatically set the cookie during the response. Your application must also be set to send the cookie with all API requests.

Following is a sample:

GET https://{domain}/me HTTP/1.1 Cookie: X-Authorization=Access_Token access_token=ajlakdsjflkasdfh8vab372iu345h3

Sample Error Response

Following a sample error response as a result of using a malformed access token.

HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Content-Length: 101 { "error":{ "message":"unauthorized", "errorId":"e097d8ea-3892-45f8-9459-065279efd983", "request":"/me" } }

Access Token Expiration

Currently, the expiration of LearningStudio RESTful API tokens is the following:

  • Access tokens - 60 minutes (token parameter expires-in=3600 seconds)
  • Refresh tokens - ≈70 minutes (same life as access token, plus a little extra time)

The expiration timeframe is static and not configurable. To continue transactions, you must renew the access token per the method described for the OAuth protocol you are using. For example, if you are using the OAuth 2.0 Password Grant type, you would use the refresh token to request a new set of access and refresh tokens for the user. If you are using the OAuth 2.0 Assertion Grant type, you must repeat the authorization request to get a new access token. See the respective pages for more details.

If you attempt an API transaction using an expired token, LearningStudio will deny your request with a 401 - Unauthorized response. Following is a sample response to a request using an expired access token.

HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Content-Length: 110 { "error":{ "message":"Authorization Expired", "errorId":"c083ecdf-96c9-46e4-9674-003745a9e165", "request":"/me" } }

3132 reads
Always Learning
Pearson