Chevron RightKensho NERDChevron Right

Authentication With Public/Private Key Pair

v1 (Latest)

Authenticating with Public/Private Keypair

This form of authentication allows users to generate a keypair, send Kensho the public key, and sign requests with their private key.

It is meant for clients who wish to deploy production services that integrate the NERD API. Individual users should instead use personal tokens (i.e., as obtained via the authentication quickstart guide) to access the API in the browser or for development.

The steps to configure authentication are as follows:

  • Generate an RSA keypair per the below instructions
  • Email support@kensho.com with your public key, and we will respond with a Client ID
  • Create and sign a JWT token using your private key
  • Use Kensho's Okta API to generate an authentication token
  • Use the returned token in API requests to NERD

Read on for detailed instructions.

RSA Authentication Guide

Generate an RSA Keypair

In this guide, we will use the openssl library, which is available on Unix systems. First, generate a 2048-bit private key using RSA:

openssl genrsa -out private.pem 2048

Next, extract the public key:

openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Send Kensho Your Public Key

Send an email to support@kensho.com with your public key. We will respond with your Client ID. This ID is not a secret.

Important: Do not send us your private key!

Create and Sign a JWT.

Most languages have JWT libraries. In this example, we make use of PyJWT, a JWT library for Python.

import jwt
import time
with open("private.pem", "rb") as f:
private_key = f.read()
client_id = "<from above email>"
iat = int(time.time())
encoded = jwt.encode(
{
"aud": "https://kensho.okta.com/oauth2/default/v1/token",
"exp": iat + (30 * 60), # expire in 30 minutes
"iat": iat,
"sub": client_id,
"iss": client_id,
},
private_key,
algorithm="RS256",
)

Generate an API Token

Make a request to Okta using the JWT to retrieve a non-expiring authentication token. Note that Content-Type is specified as application/x-www-form-urlencoded. When you call requests.post() in python, data dictionary will automatically be converted into a string formatted like this: client_assertion=xxxxxxx&scope=kensho:app:nerd&grant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer If you are using another programming language, you need to make sure you send data in the format specified above, rather than sending in JSON.

import requests
response = requests.post(
"https://kensho.okta.com/oauth2/default/v1/token",
headers={
"Content-Type": "application/x-www-form-urlencoded",
"Accept": "application/json",
},
data={
"scope": "kensho:app:nerd",
"grant_type": "client_credentials",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": encoded,
}
)
token = response.json()["access_token"]

Verify Token

To test out your new token, run

curl -H "Authorization: Bearer <your token>" https://nerd.kensho.com/me

If you get a response with your client ID, you're in the money! Head over to the Text Annotation Guide to get your first NERD annotations.

AnS&P Globalcompany

Harvard Square + AI Lab

44 Brattle St
Cambridge, MA 02138

New York City

One World Trade Center
New York, NY 10006

Washington D.C.

Tysons Corner
McLean, VA 22102
Copyright © 2021 Kensho Technologies, LLC. Kensho and Visallo marks are the property of Kensho Technologies, LLC. All rights reserved.