Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Khan Academy API Authentication

Alan Pierce edited this page · 8 revisions

About Khan Academy API Authentication

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, Google, and username/password login), 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.

Authentication Steps

The current and recommended authentication flow is version 2, which is described below. Version 1 is still supported, and you can find documentation for it on the Khan Academy Authentication Flow v1 page. Note that the "2" only refers to the authentication flow itself; the flow still uses OAuth 1 and is used to access endpoints starting with /api/v1/.

Getting started

  1. Register for an API key. Visit the Register an App page while logged into Khan Academy and fill out the form. Note that the name you enter into the form will show up when the user logs into your app. When you submit the form, you'll receive an API consumer key and an API consumer secret, which you'll use below.
  2. Check if a Khan Academy client library has already been written for your programming language. This GitHub repo includes some sample client libraries that you may be able to work off of to get started. If you find one that works for you, you may be able to skip most of the remaining steps.
  3. If not, find an OAuth library for your programming language. There are tons of OAuth client libraries out there that will help walk you through the authentication flow described below.

Try following the documentation in your OAuth library and configuring it to use these three authentication endpoints:

https://www.khanacademy.org/api/auth2/request_token
https://www.khanacademy.org/api/auth2/authorize
https://www.khanacademy.org/api/auth2/access_token

In many cases, authentication should just work. If you run into any problems, the steps below describe the process in more detail.

1. Get a request token

The first step is to obtain a request token, which will later be used to allow a user to grant your app access to their Khan Academy account.

You can get a request token by making a POST request to this URL: https://www.khanacademy.org/api/auth2/request_token

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. For security reasons, production apps should always specify this parameter.

Response format The response has a form-encoded body that contains two values: oauth_token and oauth_token_secret. The oauth_token is the request token. Here's an example:

oauth_token=t4632213944267176&oauth_token_secret=4tsVQH6L5n2TGm8R

2. Authorize your request token

Now that you have a request token, you need to have it approved by the user. To do this, you'll direct the user of your app to log into Khan Academy and agree to give your app access to their Khan Academy account data.

Start the authorize process by having the user make a GET request to the authorize URL https://www.khanacademy.org/api/auth2/authorize with the oauth_token parameter set to the request token you obtained previously.

For example, you might open the user's browser and navigate it to this URL: https://www.khanacademy.org/api/auth2/authorize?oauth_token=t4632213944267176

If the user is not already logged in, they will be asked to log into Khan Academy. Then, they will see an approval page that looks like this:

When the user clicks the "Accept" button, they will be redirected 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. The query string has the following values specified:

oauth_token - The request token, which should match the token you already have. oauth_token_secret - The request token secret, which should match the token secret you already have. oauth_verifier (if a callback was explicitly specified) - A verification string that you will used when obtaining an access token.

Alternative: logging in directly with your own account
If you are logging in as yourself (that is, the KA user who registered the API key), then you have the option to skip the browser-based approval step and approve the token directly by making a POST request with your KA credentials. This makes it easier to log in automatically without manual steps.

To do this, send a POST request to https://www.khanacademy.org/api/auth2/authorize with the following parameters in the POST body:

oauth_token (required) - The request token.
identifier (required) - Your username or an email address associated with your KA account.
password (required) - Your Khan Academy password.

The POST request must follow all redirects in order to complete the token authorization process.

If you don't have a password yet, you can always set one on your account settings page.

This action is equivalent to clicking the "Accept" button on the approval page, and will redirect to the callback you specified when getting a request token.

3. Get 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/auth2/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

4. Make an authenticated API call

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

If the user's token expires, API requests will start receiving a 401 error. When this happens, your app should ask the user to authenticate again.

API/Authentication FAQ

Do I always need to go through all of these OAuth steps to access the API?

No, you don't need to follow these steps if you are only interested in using the API to access public information that isn't specific to any particular user. For example, you can load https://www.khanacademy.org/api/v1/badges without any special authentication to get a JSON list of all badges available on Khan Academy.

However, if you want to get user-specific information (even for yourself), you need to follow these steps.

Why are there two authentication flows (/api/auth/ vs. /api/auth2/) and what are the similarities and differences between the two?

The v2 flow (/api/auth2/) was added in March 2015 to simplify the process of connecting to the Khan Academy API. The old v1 flow implemented OAuth 1 in a non-standard way, and in practice this meant that every KA client library needed to figure out how to configure or extend its OAuth 1 library in a way that works with the KA API. This meant that getting started with the API in a new programming language often required a significant amount of work.

In the new v2 flow, the request_token and authorize endpoints behave in a more standard way, so most OAuth 1 libraries should just work without requiring any special configuration.

Aside from the behavior of the request_token and authorize endpoints, the two flows are the same:

  • Both flows use OAuth 1.
  • Everything after the authentication step is the same, and both flows provide access to the same set of endpoints.
  • Any registered API consumer will work in either flow.

The endpoints exposed on the API explorer don't seem to do what I need. Am I able/allowed to access any other endpoints?

Yes! The API explorer documents our public API, which has URLs starting with /api/v1, but unfortunately it's not very well-maintained and lacking in a few areas.

If you're feeling adventurous, though, you're welcome to use any internal undocumented API endpoints. For example, if you load a Khan Academy video page and use your browser's developer tools to look at the ajax requests being sent, you'll see that it gets a URL like /api/internal/videos/aubZU0iWtgI/transcript, which contains a JSON response with the video subtitles. That "internal" in the name means that we don't provide documentation, and we may remove the endpoint or change the format in the future, but you're welcome to use any internal endpoints if you keep those caveats in mind.

Is there a place where I can send questions or report problems?

You can file an issue in this GitHub project, or you can email us at api-questions@khanacademy.org .

Unfortunately, we're not always actively developing and maintaining the API, so we're unlikely to add significant features and may be slow at responding to questions, but we try to get to every question and we hope you'll still find the existing API useful.

Something went wrong with that request. Please try again.