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 requestsREFRESH_TOKEN = "" # copy-paste your Refresh Token inside the quotation marksresponse = 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 requestsdef 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_tokenREFRESH_TOKEN = "" # copy-paste your Refresh Token inside the quotation marksACCESS_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.