Authentication Quickstart

This guide is intended for users who have an account set up and who would like to access the NERD API programatically. If you prefer a video guide for authentication, please click here.

To get started, visit the login page to sign in. When successfully logged in, you can click your email address in the top-right corner of the website and select the "Account" menu option. On the Account page, you will see your email address, a Refresh Token, and an Access Token.

Access Token

For use with basic testing

Your Access Token is your key to accessing the NERD API. You can copy it from this page and visit our Text Annotation Guide guide to use the token to submit an annotation request. This is all you need to get started!

Refresh Token

For use with longer-lived exploratory code

For security, your Access Token expires every hour, on the hour. Thus, you will need to get a new access token every once in a while. You can acquire a new Access Token by returning to the Account page or by using your Refresh Token to programatically get a new Access Token.

The Refresh Token expires every week, so using it to generate a new Access Token is perfect for short-term use cases.

In the code snippet below, we demonstrate how you can use your Refresh Token to get a new Access Token.

You simply send a request to https://nerd.kensho.com/oauth2/refresh?refresh_token=<Refresh Token>, and your new Access Token will be provided in the "access_token" section of the response.

import requests

REFRESH_TOKEN = ""  # copy-paste your Refresh Token inside the quotation marks
response = requests.get(f"https://nerd.kensho.com/oauth2/refresh?refresh_token={REFRESH_TOKEN}")
ACCESS_TOKEN = response.json()["access_token"]

We also created a helper function to make this easier for you.

import requests


def get_access_token(refresh_token):
    response = requests.get(f"https://nerd.kensho.com/oauth2/refresh?refresh_token={refresh_token}")
    if not response.ok:
        raise RuntimeError(
            "Something went wrong when trying to use NERD. Is your refresh token correct?"
        )
    access_token = response.json()["access_token"]
    return access_token


REFRESH_TOKEN = ""  # copy-paste your Refresh Token inside the quotation marks
ACCESS_TOKEN = get_access_token(REFRESH_TOKEN)

These code snippets assume you are running Python 3.6 or higher and that you have the requests library installed.

Public/Private Keypair

Use for production application integration

While copying your Access Token or Refresh Token from the web page is great for testing out the NERD API, it's not suitable for long-running applications that use NERD. In these cases, we recommend using a public/private keypair. Setting up these keys takes a little effort upfront, but afterward no maintenance is required to keep using the NERD API.

We have a separate guide for those interested in setting up public/private keypairs. For more information, you can also check out our video guide on API authentication methods.