Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Khan Academy API Authentication

alangpierce edited this page · 3 revisions

Authenticating Against the Khan Academy API

As a third-party developer, you have the option to allow a user to log into Khan Academy through an app you develop using the Khan Academy API, giving your app access to the "Login Required" calls described in the API Explorer. Your API consumer key (see the OAuth details below) is included in each call to identify you as a third-party API user. Your app may request information about the logged-in user, but your app may not access information about other users beyond the logged-in user. Such requests will be rejected, even if the data would normally be accessible to the logged-in user on the Khan Academy website. The sole exception is if a coach is also a third-party developer who is using his/her own app directly to access data on his/her own students. In other words, when the logged-in user is the same as the user who registered the API key, the user may access their own (and only their own) students' data. See here for the recommended practices for teachers and schools accessing information on their students through the API.

The Khan Academy API uses an OAuth 1.0 flow for authentication and authorization. We support multiple identity providers (Facebook and Google), so the individual flow for each user logging into the Khan Academy through your application may be slightly different. However, we handle all of that behind the scenes for you, and as a developer you only need to worry about implementing the following OAuth flow.

Have no fear! There are tons of OAuth client libraries out there that will help you set up each request's required OAuth parameters described below without much work. There's also a small sample Python client in this repo that you can run to see what a working authentication flow looks like.

You'll need to get a consumer token and secret for your app before you can start authenticating users. Once you have your consumer token and secret...

1. Getting a request token

The first thing you'll need to do is grab a request token. You do this by opening the user's browser window at or redirecting to our request token url with appropiate OAuth parameters.

/api/auth/request_token

Results
Navigates user through request token retrieval and authorization for the identity provider of their choice. Redirects to callback url specified by oauth_callback (or /api/auth/default_callback if a custom callback url is not provided) with additional OAuth parameters identifying the request token in the query string.

Parameters
oauth_consumer_key (required) - Your app's consumer key
oauth_nonce (required) - Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique.
oauth_version (required) - OAuth version used by your app. Must be "1.0" for now.
oauth_signature (required) - String generated using the referenced signature method.
oauth_signature_method (required) - Signature algorithm (currently only support "HMAC-SHA1")
oauth_timestamp (required) - Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_callback (optional) - URL to redirect to after request token is received and authorized by the user's chosen identity provider.

Results Example Once the request token is received and authorized, your user's browser will be redirected to oauth_callback url with oauth_token, oauth_secret, and, if a non-default callback url was provided, oauth_verifier parameters. Your app should detect this redirect and grab these parameters from the query string for use in the next step.

For example, your user will be redirected to: http://www.khanacademy.org/api/auth/default_callback?oauth_token=6acEfEnhsyFdS6Er&oauth_secret=T3cz27eck39Afw3

Choosing a provider

Getting an authorized request token

2. Getting an access token

Next, you'll need to exchange your request token for an access token. You don't need the user's browser for this step. You just make a request to our access token url with the proper OAuth parameters, and if successful the response will contain your access token.

/api/auth/access_token

Results
Takes request token and exchanges it for an access token which can be used to make authenticated requests.

Parameters
oauth_consumer_key (required) - Your app's consumer key
oauth_token (required) - Previously authorized request token
oauth_nonce (required) - Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique.
oauth_version (required) - OAuth version used by your app. Must be "1.0" for now.
oauth_signature (required) - String generated using the referenced signature method.
oauth_signature_method (required) - Signature algorithm (currently only support "HMAC-SHA1")
oauth_timestamp (required) - Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.
oauth_callback (optional, required if oauth_callback was supplied in the request_token step) - URL to redirect to after request token is received and authorized by the user's chosen identity provider. This url must match the callback url provided in the request_token step, if it was provided.
oauth_verifier (optional, required if oauth_callback was supplied in the request_token step) - Verifier code provided in the response to the request_token step, if an oauth_callback was originally provided.

Results Example
oauth_token=4nQCEEnhsyh65Zd6&oauth_token_secret=WzBC3t7eck3v2a7Q

3. Making authenticated API calls

Now that you have your access token, you can make requests to any of the methods that require authentication. You do so by using your OAuth client to make the request, including the following required OAuth parameters and an appropriate signature.

Parameters
oauth_consumer_key (required) - Your app's consumer key
oauth_token (required) - Your shiny new access token
oauth_nonce (required) - Random 64-bit, unsigned number encoded as an ASCII string in decimal format. The nonce/timestamp pair should always be unique.
oauth_version (required) - OAuth version used by your app. Must be "1.0" for now.
oauth_signature (required) - String generated using the referenced signature method.
oauth_signature_method (required) - Signature algorithm (currently only support "HMAC-SHA1")
oauth_timestamp (required) - Integer representing the time the request is sent. The timestamp should be expressed in number of seconds after January 1, 1970 00:00:00 GMT.

Results Example
Results vary depending on method being called. If you pass an invalid access token, you'll receive a 401 Unauthorized response.

Invalid and expired tokens

Tokens may be invalidated or expired by Google or Facebook for various reasons. In the event that you receive a 401 when providing your access token, it is up to your app to ask the user to authenticate again.

Something went wrong with that request. Please try again.