Skip to main content
Version: latest

Authenticate to Python Library

This page provides instructions for authenticating to the Cortex-Python library.

info

For all authentication methods: Before you can authenticate, you must install the Cortex Python libraries in your Python development environment.

A couple of authentication methods are described in this document. Use the one that applies to your use case.

  • Authenticate in a development environment or Jupyter notebook
  • Authenticate within a deployed action (job/daemon)
  • Authenticate in an interactive python environment

Environmental Variables​

The Python Library can be configured with several environment variables as described in each of the methods. The available environment variables are:

  • CORTEX_TOKEN - Sets the JWT for usage with the Python Library (not the CLI).

  • CORTEX_PERSONAL_ACCESS_CONFIG - Sets the path to your Personal access token (PAT file) for the Python Library (not the CLI). Useful if you have a pat.json file, but don’t have the CLI. If not set, then the CLI's default profile (PAT) is used.

  • CORTEX_PROJECT - default project, used by both the CLI and the Python lib.

  • CORTEX_URI - URI for your Fabric Instance, used by both clients.

If your SENSA Fabric instance uses self signed certificates, you'll also need to set these additional environment variables to authenticate against the cluster.

note

For the environment variables needed to enable communication and authentication to a SENSA Fabric instance configured with self signed certificates, you'll need to talk to your IT administrator or DevOps team to get access the CA bundle file used for the instance.

Authenticate in an IDE or Jupyter notebook​

The Cortex.client() API requires the Cortex URL, personal access token, and the project context to authenticate. These can be provided to the API in three ways:

  • Using the Cortex Node.js CLI
  • Passing the values programmatically
  • Passing the values through environment variables

The Cortex.client() method retrieves the clients credentials (api_endpoint, api_version, verify_ssl_cert, token, config, and project) with the following priority:

  1. Parameters passed into the Cortex.client() method
  2. Environment variables (e.g. CORTEX_PERSONAL_ACCESS_CONFIG or CORTEX_PROJECT)
  3. The default CLI profile

The API uses the currently selected default profile. For multiple cortex profiles use cortex configure set-profile <profile> to select different profiles.

Within your IDE or text editor, authenticate to Cortex using the Cortex.client() method:

from cortex import Cortex
client_instance = Cortex.client()

This creates an authenticated instance of the cortex client by checking for environment variables.

If any values are missing, the cortex-python libraries will retrieve them from your default CLI profile.

We recommend using Cortex CLI's profiles over environment variables or passing optional parameters to the client() method. The Cortex.client() API will first check environment variables and then Cortex client configuration for URL, token, and project if not provided.

The Cortex.client() method has the following optional parameters:

  • api_endpoint: API endpoint ( default: None )
  • api_version: Cortex api version ( default: 4 )
    • verify_ssl_cert: Validate https certificate True|False|<certificate bundle location> (default: True)
  • token: JWT token ( default: None )
  • config: Cortex Personal Access Config ( default: None )
  • project: Cortex Project that you want to authenticate to ( default: None )

At runtime it is typically only necessary to pass a valid token and api_endpoint in order to actually create a valid cortex client instance.

Alternatively, you may provide your credentials or JWT token when creating your client instance, but this is NOT recommended unless you are testing/developing code locally and your environment doesn't support the Cortex CLI or interactive logins.

client_instance = Cortex.client(api_endpoint='https://api.cortex.insights.ai',
                                token='<your-JWT>'

or alternatively

client_instance = Cortex.client(api_endpoint='https://api.cortex.insights.ai',
                                token='<your-personal access token>',
                                project='<your-project context>',

Authenticate into a Client class​

The client instance created from Cortex.client() can be passed into any of the Client classes provided with the Cortex python library. For example:

from cortex import Cortex
from cortex.content import ManagedContentClient
 # read from ~/.cortex/config and provide custom SSL certs.
client = Cortex.client(verify_ssl_cert="/etc/ssl/certs/ca-certificates.crt")
fileData = ManagedContentClient(client).download('myfile').data

To configure a Cortex client connection with custom SSL certificates, specify the following environment variable REQUESTS_CA_BUNDLE=<crt bundle location> or pass verify_ssl_cert=<crt bundle location> to Cortex.client()

Authenticate within a deployed Skill​

Cortex Skills are provided a JWT token within a message with each invocation snapshots. The command-line args must be parsed via the Message helper class and passed to Cortex.from_message() to get a client connection.

from cortex import Cortex, Message

def main(params):
    """ A deployed skill that will need a cortex client snapshot. """
    msg = Message(params)
    client_instance = Cortex.from_message(msg)
    ### your code below

Authenticate in an interactive python environment​

An interactive environment is one where a user is able to provide input to the program while it is running such as: JuptyterLab Notebooks, PyCharm, or your terminal.

In an interactive environment you can authenticate using the Cortex.login() method. This authentication is temporarily cached, so you will have repeat the authentication each time you execute the program. Hence, we do not recommend this approach, and suggest installing and configuring the Cortex CLI if possible.

from cortex import Cortex

## Begins an interactive prompt that will ask for your login credentials
Cortex.login()

## An instance of the cortex client will be created using the previously provided credentials
client_instance = Cortex.client()

When executed the above python file from your terminal, the following response is returned:

> python test.py

Cortex URI: [https://api.cortex.insights.ai]
Personal Access Config: personal access token
Cortex Project name: Project you want to access

NOTE: If you execute the above program from a JupyterLab notebook, entry fields appear for each of the input arguments.

JWT expiration​

Cortex JWT tokens expire and must be periodically renewed. When your token expires, you will receive a BadTokenException or the client creation will fail. You must re-authenticate to refresh your token.

CORTEX_TOKEN error​

When using the Cortex-python libraries in your own Integrated Development Environment, you might receive the error Your Cortex credentials could not be retrieved. This error occurs when:

  • a valid JWT token does not exist (For example, if you run print(os.environ['CORTEX_TOKEN']) and a JWT token is not returned). To fix, open a terminal in your IDE and run cortex configure or use the Cortex.Login method.
  • a CORTEX_TOKEN environment variable exists but is set to an empty string or an invalid string (For example, CORTEX_TOKEN=" " or CORTEX_TOKEN='asda'). To fix, remove the empty or invalid string from your CORTEX_TOKEN.
  • a valid JWT token exists but is expired or a JWT token exists and is not a valid CORTEX_TOKEN. To fix, refresh your JWT token and pass the Cortex URL and your JWT token directly to the Cortex Client: Cortex.client(api_endpoint='https://api.<dci-base-domain>', token=<your JWT token>).