Authentication
Production Authentication

Public-Private keypair authentication

Public/Private keypair authentication is recommended when using Kensho APIs for production use cases. While it requires some additional setup, this method is the most secure and easy way to use Kensho APIs 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

Create your keypair below. It is generated locally in your browser, so your private key is never sent to Kensho.

Prefer to generate the keypair yourself?

You may generate the keypair yourself with any tooling you prefer. Represent your public key as a JSON Web Key (JWK), formatted exactly like the example below and containing those exact fields. It must be RSA 2048-bit or larger.

{
  "kty": "RSA",
  "kid": "<your-key-id>",
  "use": "sig",
  "n": "<base64url-modulus>",
  "e": "AQAB"
}

Save this JWK as public-key.json and send it to Kensho as described below.

Send Kensho your public key

Important note

Do not send us your private key! While your public key and Client ID are not secret, your private key should not be shared outside of your organization.

Email support@kensho.com the following information:

  1. Your public key: attach public-key.json (not private-key.pem).
  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-key.pem key file combination can be seen below.

import jwt
import requests
import time
 
# Include only the scopes for the Kensho applications you have access to. Requesting a scope that
# your Client ID does not have permission to use will cause this token request to fail.
ALL_APPLICATION_SCOPES = "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-key.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),
            "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.