Public-Private keypair authentication

Public/Private keypair authentication is recommended when using Kensho API for production use cases. While it requires some additional setup, this method is the most secure and easy way to use Kensho in the long term. For testing and development, individual users should check out the authentication basics.

Authenticating with keys requires a number of steps:

1. Generate a keypair.
2. Send Kensho your public key.
3. Obtain an access token.

Generating an RSA keypair

In this guide, we will use the OpenSSL (opens in a new tab) library, which is available on Unix systems (which includes Macs). First, open a terminal and generate a 2048-bit private key:

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

Email support@kensho.com the following information:

1. Your PEM encoded public key as an attachment.
2. The Kensho application(s) you would like to access. For a list of all available applications, please see Kensho's solutions (opens in a new tab) page.

We will respond with your Client ID. You will need this ID in the following step. While typical response times are quick, please allow up to three business days for us to process your request.

Obtaining an Access Token

Once Kensho has sent a Client ID, it can be used, in conjunction with the private key above, to generate a usable access token. Sample code to convert a Client ID and private.pem key file combination can be seen below.

Unlike with refresh tokens, access tokens generated through this method can have a custom expiration defined in the exp field and be up to 60 minutes maximum.

import jwt
import requests
import time
 
ALL_APPLICATION_SCOPES = "kensho:app:classify kensho:app:scribe kensho:app:nerd kensho:app:link kensho:app:caterpillar"
 
def get_access_token_from_key(client_id, scope=ALL_APPLICATION_SCOPES):
 
    PRIVATE_KEY_PATH = "private.pem"  # the location of your generated private key file
    with open(PRIVATE_KEY_PATH, "rb") as f:
        private_key = f.read()
 
    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",
    )
    response = requests.post(
        "https://kensho.okta.com/oauth2/default/v1/token",
        headers={
            "Content-Type": "application/x-www-form-urlencoded",
            "Accept": "application/json",
        },
        data={
            "scope": scope,
            "grant_type": "client_credentials",
            "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
            "client_assertion": encoded,
        }
    )
    return response.json()["access_token"]
 
CLIENT_ID = ""  # paste your Client ID sent to you by Kensho inside the quotation marks
# Override the scope parameter if your application only needs access to select Kensho APIs
ACCESS_TOKEN = get_access_token_from_key(CLIENT_ID)

Verify token

To validate that an access token works for the application you are accessing, run

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

If the response status is 200, then the token is valid.