How to authenticate and query edX APIs with Postman

Owned by Andy Shultz (Deactivated)
Last updated: Aug 17, 2022 by Nathan Sprenkle
4 min read

(this article originally by @Nathan Sprenkle and @Zach Hancock in the 2U space)

Note: although this article is Postman specific, many of the techniques can probably be adapted for other API query tools.

Working on a recent API development project, I found myself needing a tool for robustly exercising an API. Postman is a super helpful tool for doing just that, but there was nothing in our docs (that I could find) about working with logon sessions and auth-related stuff, in particular. Here’s a quick how-to on authenticating with Postman and hitting APIs.

First things first: go to the Postman downloads page to download/install Postman.

Scripted processes:

  1. Download Postman

  2. Run Login collection scripts or obtain API JWT

Manual process:

  1. Download Postman

  2. Steal some cookies

  3. CSRF token setup

  4. Profit!

Scripted Process

I got annoyed by having to do the manual process each time so I borrowed an approach from this Medium post and adapted for LMS. I’m attaching the collection here so you too can log in from Postman.

  1. Download my collection of scripts for LMS

  2. Update environment variables

  3. Run the GET Login script

  4. Run the POST Login script

  5. You’re authenticated!

Download LMS collection

Here is the LMS Postman collection. Download it then follow Postman instructions for importing a collection.

Update environment variables

To avoid hard-coding everything, the collection expects a few variables to be set before running. See Postman instructions for setting variables to set the following:

  • lms_url - For Devstack this is localhost:18000

  • protocol - Either http or https, depending on if you’re testing with HTTPS or not

  • user_email - The user you’re going to log in as, e.g. staff@example.com

  • user_password - The user’s password, e.g. edx

Run the GET Login script

This gets the login form you would normally see logging on to the LMS. Importantly, the test scripts in this call extract the CSRF token and save it in an environment variable (csrftoken) for later use.

Run the POST Login script

This logs in as the user specified by user_email and user_password

You’re Authenticated!

To connect CSRF token to requests add the CSRF token header to requests. Re-run the GET/POST scripts if the token times out or you log out.

X-CSRFToken: {{csrftoken}}

Scripted Process with OAuth Client

This is a similar approach to the scripted process above but by authenticating an an OAuth application we can avoid the need to deal with CSRF tokens and cookies. I find this simpler to manage.

Create an OAuth application

Create a new application at: http://localhost:18000/admin/oauth2_provider/application/

  1. user the user you want to authenticate as

  2. client type confidential

  3. Authorization grant type client credentials

  4. name whatever you want, you will need this to more easily find your record again in django admin

  5. keep track of your client id in secret, we’ll need these later

Update environment variables

To avoid hard-coding everything, the collection below expects a few variables to be set before running. See Postman instructions for setting variables to set the following:

  • LMS_BASE - For Devstack this is localhost:18000

  • API_CLIENT_ID - client id from the application you created above

  • API_CLIENT_SECRET - client secret from the application you created above

Obtain a JWT token

POST to the /oauth2/access_token/ endpoint using your client_id and secret.

This is configured for you as the Access Token endpoint in the collection shared below

You’re Authenticated!

Future requests simply need an Authorization: JWT {{YOUR_TOKEN}} in the header. Each of the requests in the collection shared below include this.

My postman collection

Manual Process

A higher-effort approach, but one that explains how cookie auth and CSRF work with edx-platform and how to borrow an active login session.

Steal some cookies

The tricky bit about querying anything tied to edx-platform is auth. To become the hackerman authenticate, we’re gonna need some cookies. Specifically, to masquerade as a logged in user, we need to capture an active session cookie. There are a few ways to do this which Postman documents here. I use the Postman interceptor approach but could also be done with the Postman Proxy or vanilla browser tools. I like the interceptor because it loads cookies right into the app so there’s no copy/paste, etc.

The punch line: capture an cookie for your active user, should look something like the below:

csrftoken=<csrf-jibberish>; edx-jwt-cookie-header-payload=<jwt-thingy>; edx-jwt-cookie-signature=<signature>; edx-user-info=<json-blob>; edxloggedin=<true/false>; experiments_is_enterprise=<true/false>; lms_sessionid=<session-jibberish>; openedx-language-preference=<en/more-exciting-language-code>

CSRF token setup

Cookie thief! The council of cookie protectors will have your head for this. It’s okay, I won’t rat you out.

Moving on, even though the CSRF token is in the cookie, LMS expects it in a header. Grumble, grumble, brevity being the soul of wit or whatever…

In Postman, go to the Headers tab of the request. Add a new header called X-CSRFToken. Copy and paste the value from the csrftoken in the cookie into the value for the header. It should look something like the below:

Profit!

You did it! Make some queries with your sweet new authenticated self!