Authentication
Authentication Quickstart

Authenticating with a personal token

Prerequisites

The examples on this page assume the following software packages are installed and accessible:

# All Shell examples on this page require the following:
- curl (https://everything.curl.dev/get)

Refresh tokens

Refresh tokens are short strings which can be used to generate access tokens for API calls. Refresh tokens expire seven days after their last use, making them a great option for short-term API access. It is not advised to use them in production workflow scenarios unless the API is used at least once a week.

To obtain a refresh token, visit the website corresponding to the Kensho API that you'd like to access.

Refresh tokens cannot be directly used in API calls (only access tokens can). The sample code below illustrates how refresh tokens can be used to generate access tokens.

Note

Refresh tokens can only be used to generate access tokens for the API that they correspond to. For instance, a Scribe refresh token cannot be used to generate access tokens for NERD.

Note that each Kensho API has its own refresh token endpoint, so be sure to use the URL corresponding to the API you'd like to access.

curl https://scribe.kensho.com/oauth2/refresh?refresh_token=<Refresh Token>

If your refresh token is valid, you should see an access token in the response:

{
  "access_token": "..."
}

Automatically refreshing an access token

When using a refresh token to generate access tokens to a Kensho API, the access token will expire after a short period of time. In production use cases it's recommended to automatically refresh the access token after it expires. There are a number of approaches to accomplish this, we've provided an example refresh flow in Python below (this example requires PyJWT (opens in a new tab) to be installed):

import requests
import time
import jwt
 
REFRESH_TOKEN = "" # copy-paste your Refresh Token inside the quotation marks
access_token = None
access_token_expiration = 0
 
def get_access_token():
 
    global access_token_expiration
    # If the access token is valid for the next minute, don't refresh it
    if time.time() + 60 < access_token_expiration:
        return access_token
 
    # The token will expire or has already expired, so refresh it.
    response = requests.get(f"https://<Kensho API>.kensho.com/oauth2/refresh?refresh_token={REFRESH_TOKEN}")
    if not response.ok:
        raise RuntimeError(
        "Something went wrong when trying to access this API. Is your refresh token correct?"
        )
    response_json = response.json()
    access_token = response_json.get("access_token")
    access_token_expiration = jwt.decode(access_token, options={"verify_signature": False}).get("exp")
 
    return access_token
 
ACCESS_TOKEN = get_access_token()

Note

For security purposes, you will be required to obtain a new access token every hour. The code sample above will automatically refresh the access token prior to expiration.

Another option for automatically refreshing access tokens would be to use a library like Requests-OAuthlib (opens in a new tab), which has built in utilities for automatically refreshing an access token.

Get a new refresh token in case of expiration

Refresh tokens are valid for 7 days after their latest use. In the event that your token expires, you will need to update your code to use a new token. Refer to Refresh tokens above for a new token.

Advanced authentication

In more advanced use cases, like a long running API integrated with a Kensho service, it's recommended to use a public-private keypair for authentication. See the advanced authentication for more information.