Ready to get an auth token? See our Authentication API reference.

In this section:

• Authentication
  • Understanding The 2-Legged OAuth Flow
  • Using Your OAuth Access Tokens
  • Legacy Fine-Grained Authorization

Authentication

Learning applications typically enforce rules to restrict the data and operations that users can access. Data and operations provided through Knewton APIs are no exception - the learning application is responsible for preventing Knewton API requests from being made on behalf of users that should not be authorized to make those requests, and for implementing appropriate restrictions on user-level visibility of data returned by the Knewton API.

The Knewton Platform, in turn, enforces that only authorized partners can invoke Knewton APIs, and that each partner learning application can access only its own resources via Knewton APIs. Every Knewton API request must include an Authorization header with an appropriate value:

• POST /oauth/token: Use the Basic Authentication Scheme to exchange the partner admin credentials for an OAuth access token that grants access to all resources owned by the partner.
• All other endpoints: Use Bearer Authentication Scheme to pass an OAuth access token to identify the calling partner and authorize the request.

Looking for your partner admin credentials? See Partner Credentials.

Understanding The 2-Legged OAuth Flow

Consider the OAuth 2.0 protocol’s role schema. In the Knewton Platform’s security model, the partner learning application acts as both the client and the resource owner, while the Knewton Platform acts as both the resource server and the authorization server. Since there are only two parties involved in this security model, we avoid the more complex OAuth flows. Instead, each partner learning application has a single partner admin user who is considered the owner of all of the Knewton API resources created by the partner, and there is only a single authorization scope for each partner, identified by the ID of the partner admin user. This partner admin user is provisioned by Knewton and its details are securely shared with the partner at the start of an integration. These shared partner admin data include all the values needed to perform a 2-legged OAuth Client Credentials Grant to obtain an OAuth access token that can be used to authorize subsequent requests to the API. Cross-reference the shared partner admin data and the Authentication API docs to form your request:

Curl Example:

curl -X POST \
  -u <client_id>:<client_secret> \
  -d "grant_type=client_credentials&scope=<external_user_id>" \
  https://api.knewton.com/v0/oauth/token

Example Response

{
  "access_token": "79c1260bbe754eadb12084aa1db86a9e",
  "token_type": "Bearer",
  "expires_in": 3599,
  "refresh_token": "1be6ce4a1e764904aad2f079f88cb393",
  "scope": "*",
  "account_id":"85b95240-b8e6-11e2-9e96-0800200c9a66",
  "expires_at": "2014-01-06T21:10:57.588Z"
}

Using Your OAuth Access Tokens

Use the access_token from the POST /oauth/token response body to authorize a request to another Knewton API by setting the Authorization header for the request to Bearer <access_token>.

Caching and Refreshing

All access tokens have a limited lifetime that is communicated to the learning application through the expires_in and expires_at fields of the POST /oauth/token response body. Once a token expires, it can no longer be used to authorize requests to Knewton APIs; a request that uses an expired token will result in a 401 - Unauthorized response.

The access_token field of the POST /oauth/token response should be extracted and cached so that it can be reused until it expires. When the token expires, a new one should be fetched to replace the cached token. The most common strategies for determining when to perform this refresh are:

• Storing the expires_at alongside the cached access_token, and checking before each use of the access_token whether expires_at is close to being past.
• Reusing the token until a 401 - Unauthorized response is received.

Legacy Fine-Grained Authorization

The Knewton platform also keeps track of the end-user Accounts that have access to each resource based on the Registrations and Learning Instance Roles of the Account and of the resources being accessed. For example, an analytic value for a learner registration can be accessed by the Account that owns that learner Registration, and by any Account that owns an instructor Registration in the Learning Instance to which the learner Registration belongs.

Rather than using a partner admin access token to authorize all Knewton API requests, a partner learning application may choose to manage a separate access token for each end user, and to to use the access token of the user on whose behalf a request is being made when forming the Authorization header for a Knewton API request. The additional fine-grained authorization checks performed by the Knewton Platform in this scenario are almost certain to be redundant with the learning application’s own access controls, and managing tokens independently for every end-user adds significant complexity to a Knewton API integration, so this approach is not recommended in most cases.